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The User's Guide tells you 

how to use this product; the 

Library Reference and the 

Programmers Guide focus 

on Pascal and programming 

issues. 



This manual contains definitions of all the Turbo Pascal library 
routines, along with example program code to illustrate how to 
use most of these procedures and functions. 

If you are new to Pascal programming, you should first read the 
User's Guide. The introduction to that book details the many 
features of Turbo Pascal and summarizes the contents of all four 
volumes in this manual set. In the User's Guide you'll also find 
reference information on the IDE, the project manager, the editor, 
and the command-line compilers. 

The Programmer's Guide summarizes Turbo Pascal's implemen- 
tation of the Pascal language and discusses some advanced pro- 
gramming topics. Run-time and compile-time error messages are 
in Appendix A, "Error messages." 



What's in this manual 



Chapter 1 : Run-time library is an alphabetical reference of all 
Turbo Pascal library procedures and functions. Each entry gives 
syntax, an operative description, return values if necessary, 
together with a reference fist of related routines and an example 
that demonstrates how the routines are used. 



Introduction 
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The run-time library 



This chapter contains a detailed description of all the procedures 
and functions in Turbo Pascal. The following sample library 
lookup entry explains where to look for details about each Turbo 
Pascal procedure and function. 



Sample procedure 



Unit it occupies 



Function What it does 

Declaration How it's declared; italicized items are user-defined 

Result type What it returns if it's a function 

Remarks General information about the procedure or function 

Restrictions Special requirements or items to watch for 

See also Related procedures and functions 

Example { Here you'll find a sample program that shows the use of the procedure 
or function in that entry. } 
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Abs function 



Function Returns the absolute value of the argument. 

Declaration Abs (X) 

Result type Same type as parameter. 

Remarks X is an integer-type or real-type expression. The result, of the same type 
as X, is the absolute value of X. 



Example 



var 

r: Real; 

i: Integer; 
begin 

r := Abs (-2.3); 

i := Abs (-157) ; 
end. 



{ 2.3 } 
{ 157 } 



Addr function 



Function Returns the address of a specified object. 
Declaration Addr (X) 
Result type Pointer 

Remarks X is any variable, or a procedure or function identifier. The result is a 
pointer that points to X. Like nil, the result of Addr is assignment 
compatible with all pointer types. 

E^> The @ operator produces the same result as Addr. 

See also Ofs, Ptr, Seg 

Example vac 

P: Pointer; 
begin 

P := Addr(P); { Now points to itself } 
end. 
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Append procedure 



Function Opens an existing file for appending. 

Declaration Append (var F: Text) 

Remarks F is a text-file variable that must have been associated with an external file 
using Assign. 

Append opens the existing external file with the name assigned to F. It is 
an error if there is no existing external file of the given name. If F was 
already open, it is first closed and then re-opened. The current file 
position is set to the end of the file. 

If a Ctrl-Z (ASCII 26) is present in the last 128-by te block of the file, the 
current file position is set to overwrite the first Ctrl-Z In the block. In this 
way, text can be appended to a file that terminates with a Ctrl-Z. 

If F was assigned an empty name, such as Assign(F, "), then, after the call 
to Append, F will refer to the standard output file (standard handle 
number 1). 

After a call to Append, F becomes write-only, and the file pointer is at end- 
of-ffle. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

See also Assign, Close, Reset, Rewrite 

Example V ar F: Text; 



var F: 
begin 

Assign (F, 'TEST.TXT'); 
Rewrite (F); 

Writeln(F, 'original text' ) ; 
Close (F) ; 
Append (F) ; 

Writeln(F, 'appended text' ) ; 
Close (F); 
end. 



{ Create new file } 

{ Close file, save changes } 
{ Add more text onto end } 

{ Close file, save changes } 
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Arc procedure 



Graph 



Function Draws a circular arc from start angle to end angle, using (X, Y) as the 
center point. 

Declaration Arc(X, Y: Integer; StAngle, EndAngle,' Radius: Word) 

Remarks Draws a circular arc around (X, Y), with a radius of Radius. The Arc travels 
from StAngle to EndAngle and is drawn in the current drawing color. 

Each graphics driver contains an aspect ratio that is used by Circle, Arc, 
and PieSlice. A start angle of and an end angle of 360 will draw a 
complete circle. The angles for Arc, Ellipse, and PieSlice are counter- 
clockwise with degrees at 3 o'clock, 90 degrees at 12 o'clock, and so on. 
Information about the last call to Arc can be retrieved with a call to 
GetArcCoords. 

Restrictions Must be in graphics mode. 

See also Circle, Ellipse, FillEllipse, GetArcCoords, GetAspectRatio, PieSlice, Sector, 
SetAspectRatio 

Example uses Graph; 
var 

Gd, Gm: Integer; 

Radius: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, " ) ; 

if GraphResult <> grOk then 
Halt(l); 

for Radius := 1 to 5 do 
Arc (100, 100, 0, 90, Radius * 10); 

Readln; 

CloseGraph; 
end. 



ArcTan function 

Function Returns the arctangent of the argument. 

Declaration ArcTan (x: Real) 
Result type Real 

Remarks X is a real-type expression. The result is the principal value, in radians, of 
the arctangent of X. 
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See also 


Cos, Sin 


Example 


var 




R: Real; 




begin 




R := ArcTan (Pi); 




end. 



Assign procedure 



Function Assigns the name of an external file to a file variable. 

Declaration Assign (var F; Name: String) 

Remarks F is a file variable of any file type, and Name is a string-type expression. 
All further operations on F will operate on the external file with the file 
name Name. 

After a call to Assign, the association between F and the external file 
continues to exist until another Assign is done on F. 

A file name consists of a path of zero or more directory names separated 
by backslashes, followed by the actual file name: 

Drive :\DirName\. . .\DirName\FileName 

If the path begins with a backslash, it starts in the root directory; 
otherwise, it starts in the current directory. 

Drive is a disk drive identifier (A-Z). If Drive and the colon are omitted, 
the default drive is used. \DirName\...\DirName is the root directory and 
subdirectory path to the file name. FileName consists of a name of up to 
eight characters, optionally followed by a period and an extension of up to 
three characters. 

The maximum length of the entire file name is 79 characters. 

A special case arises when Name is an empty string; that is, when 
Length(Name) is zero. In that case, F becomes associated with the standard 
input or standard output file. These special files allow a program to utilize 
the I/O redirection feature of the DOS operating system. If assigned an 
empty name, then after a call to Reset(F), F will refer to the standard input 
file, and after a call to Rewrite(F), F will refer to the standard output file. 

Restrictions Assign must never be used on an open file. 

See also Append, Close, Reset, Rewrite 
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Assign procedure 



Example { Try redirecting this program from DOS to PRN, disk file, etc. } 
var F: Text; 
begin 



Assign (F, " ) ; 
Rewrite (F) ; 

Writeln(F, 'standard output. 
Close (F); 
end. 



{ Standard output } 



.'); 



AssignCrt procedure 



Crt 



Function Associates a text file with the CRT. 
Declaration AssignCrt (var F: Text) 

Remarks AssignCrt works exactly like the Assign standard procedure except that no 
file name is specified. Instead, the text file is associated with the CRT. 

This allows faster output (and input) than would normally be possible 
using standard output (or input). 

Example uses crt; 
var 

F: Text; 
begin 

Write ('Output to screen or printer [S, P]? '); 
if UpCase (ReadKey) = 'P' then 

Assign (F, 'PRN') { Output to printer } 

else 

AssignCrt (F) ; { Output to screen, use fast CRT routines } 

Rewrite (F) ; 

Writeln(F, 'Fast output via CRT routines...'); 
Close (F) ; 
end. 



Bar procedure 



Graph 



Function Draws a bar using the current fill style and color. 

Declaration Bar(Xl, Yl, X2, Y2: Integer) 

Remarks Draws a filled-in rectangle (used in bar charts, for example). Uses the 
pattern and color defined by SetFillStyle or SetFWPattern. To draw an 
outlined bar, call Bar3D with a depth of zero. 
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Restrictions Must be in graphics mode. 

See also Bar3D, GraphResult, SetFillStyle, SetFillPattern, SetLineStyle 

Example use s Graph; 
var 

Gd, Gm: Integer; 

I, Width: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

Width := 10; 

for I := 1 to 5 do 
Bar(I * Width, I * 10, Succ(I) * Width, 200); 

Readln; 

CloseGraph; 
end. 
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Bar3D procedure 



Graph 



Function Draws a 3-D bar using the current fill style and color. 

Declaration Bar3D(Xl, Yl, X2, Y2: Integer; Depth: Word; Top: Boolean) 

Remarks Draws a filled-in, three-dimensional bar. Uses the pattern and color 

defined by SetFillStyle or SetFillPattern. The 3-D outline of the bar is drawn 
in the current line style and color as set by SetLineStyle and SetColor. Depth 
is the number of pixels deep of the 3-D outline. If Top is True, a 3-D top is 
put on the bar; if fop is False, no top is put on the bar (making it possible 
to stack several bars on top one another). 

A typical depth could be calculated by taking 25% of the width of the bar: 

Bar3D(Xl, Yl, X2, Y2, (X2 - XI + 1) div 4, TopOn); 

The following constants are defined: 

const 

TopOn = True; 
TopOff = False; 

Restrictions Must be in graphics mode. 

See also Bar, GraphResult, SetFillPattern, SetFillStyle, SetLineStyle 



Chapter I The run-time library 



Bar3D procedure 



Example uses Graph; 
var 

Gd, Gm: Integer; 

YO, Yl, Y2, XI, X2: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

YO := 10; 

Yl := 60; 

Y2 := 110; 

XI := 10; 

X2 := 50; 

Bar3D(Xl, YO, X2, Yl, 10, TopOn) ; 

Bar3D(Xl, Yl, X2, Y2, 10, TopOf f ) ; 

Readln; 

CloseGraph; 
end. 



BlockRead procedure 



Function Reads one or more records into a variable. 

Declaration BlockRead (var F: file; var Buf; Count: Word [ ; var Result: Word ] ) 

Remarks F is an untyped file variable, Buf is any variable, Count is an expression of 
type Word, and Result is a variable of type Word. 

BlockRead reads Count or less records from the file F into memory, starting 
at the first byte occupied by Buf. The actual number of complete records 
read (less than or equal to Count) is returned in the optional parameter 
Result. If Result is not specified, an I/O error will occur if the number read 
is not equal to Count. 

The entire block transferred occupies at most Count * RecSize bytes, where 
RecSize is the record size specified when the file was opened (or 128 if it 
was omitted). Ifs an error if Count * RecSize is greater than 65,535 (64K). 

Result is an optional parameter. Here is how it works: If the entire block 
was transferred, Result will be equal to Count on return. Otherwise, if 
Result is less than Count, the end of the file was reached before the transfer 
was completed. In that case, if the file's record size is greater than one, 
Result returns the number of complete records read; that is, a possible last 
partial record is not included in Result. 
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The current file position is advanced by Result records as an effect of the 
BlockRead. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 



I 



Restrictions File must be open. 



See also BlockWrite 

Example program CopyFile; 

{ Simple, fast file copy program with NO error-checking } 
var 

FromF, ToF: file; 

NumRead, NumWritten: Word; 

Buf: array[1..2048] of Char; 
begin 

Assign (FromF, ParamStr (1) ) ; 

Reset (FromF, 1); 

Assign (ToF, ParamStr (2) ) ; 

Rewrite (ToF, 1); 

WritelnC Copying ', FileSize (FromF) , ' bytes...'); 

repeat 
BlockRead (FromF, Buf, SizeOf(Buf), NumRead); 
BlockWrite (ToF, Buf, NumRead, NumWritten); 

until (NumRead = 0) or (NumWritten <> NumRead) ; 

Close (FromF) ; 

Close (ToF) ; 
end. 



{ Open input file 

{ Record size = 1 

{ Open output file 

{ Record size = 1 



BlockWrite procedure 



Function Writes one or more records from a variable. 

Declaration BlockWrite (BlockWrite (var F:file; var Buf; Count: Word [ ; var Result: Word ] ) 

Remarks F is an untyped file variable, Buf is any variable, Count is an expression of 
type Word, and Result is a variable of type Word. 

BlockWrite writes Count or less records to the file F from memory, starting 
at the first byte occupied by Buf. The actual number of complete records 
written (less than or equal to Count) is returned in the optional parameter 
Result. If Result is not specified, an I/O error will occur if the number 
written is not equal to Count. 
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BlockWrite procedure 



The entire block transferred occupies at most Count * RecSize bytes, where 
RecSize is the record size specified when the file was opened (or 128 if it 
was omitted). It is an error if Count * RecSize is greater than 65,535 (64K). 

Result is an optional parameter. Here is how it works: If the entire block 
was transferred, Result will be equal to Count on return. Otherwise, if 
Result is less than Count, the disk became full before the transfer was 
completed. In that case, if the file's record size is greater than one, Result 
returns the number of complete records written; that is, it's possible a 
remaining partial record is not included in Result. 

The current file position is advanced by Result records as an effect of the 
BlockWrite. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Restrictions File must be open. 

See also BlockRead 

Example See example for BlockRead. 



ChDir procedure 



Function Changes the current directory. 

Declaration ChDir(S: String) 

Remarks S is a string-type expression. The current directory is changed to a path 
specified by S. If S specifies a drive letter, the current drive is also 
changed. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

See also GetDir, MkDir, RmDir 

Example begin 

{$1-} 

{ Get directory name from command line } 
ChDir (ParamStr(l)); 
if IOResult <> then 
WritelnC Cannot find directory'); 
end. 
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Chr function 



i 



Function Returns a character with a specified ordinal number. 
Declaration chr(X: Byte) 
Result type Char 

Remarks X is an integer-type expression. The result is the character with an ordinal 
value (ASCII value) of X. 

See also Ord 

Example uses Printer; 
begin 

Writeln(Lst, Chr (12)); { Send formfeed to printer } 

end. 



Circle procedure 



Graph 



Function Draws a circle using (X, Y) as the center point. 

Declaration Circle (X, Y: Integer; Radius: Word) 

Remarks The circle is drawn in the current color set by SetColor. Each graphics 
driver contains an aspect ratio that is used by Circle, Arc, and PieSlice to 
make circles. 

Restrictions Must be in graphics mode. 

See also Arc, Ellipse, FillEllipse, GetArcCoords, GetAspectRatio, PieSlice, Sector, 
SetAspectRatio 

Example use s Graph; 
var 

Gd, Gm: Integer; 
Radius: Integer; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
for Radius := 1 to 5 do 

Circle (100, 100, Radius * 10); 
Readln; 
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Circle procedure 



CloseGraph; 
end. 



ClearDevice procedure 



Graph 



Function Clears the graphics screen and prepares it for output. 

Declaration ClearDevice 

Remarks ClearDevice moves the current pointer to (0, 0), clears the screen using the 
background color set by SetBkColor, and prepares it for output. 

Restrictions Must be in graphics mode. 

See also ClearViewPort, CloseGraph, GraphDefaults, InitGraph, RestoreCrtMode, 
SetGraphMode 

Example uses C rt, Graph; 
var 

Gd, Gm: Integer; 
begin 
Gd := Detect; 
InitGraph (Gd, Gm, "); 
if GraphResult <> grOk then 

Halt(l); 
Randomize; 
repeat 

LineTo (Random (200) , Random (2 00) ) ; 
until KeyPressed; 
ClearDevice; 
Readln; 
CloseGraph; 
end. 



ClearViewPort procedure 



Graph 



Function Clears the current viewport. 

Declaration ClearViewPort 

Remarks Sets the fill color to the background color (Palette[0]), calls Bar, and moves 
the current pointer to (0, 0). 

Restrictions Must be in graphics mode. 

See also Bar, ClearDevice, GetViewSettings, SetViezvPort 
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ClearViewPort procedure 



Example US es Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

Rectangle (19, 19, GetMaxX - 19, GetMaxY - 19); 

SetViewPort(20, 20, GetMaxX - 20, GetMaxY - 20, ClipOn) ; 

OutTextXY(0, 0, '<ENTER> clears viewport:'); 

Readln; 

ClearViewPort; 

OutTextXY(0, 0, '<ENTER> to quit:'); 

Readln; 

CloseGraph; 
end. 
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Close procedure 



Function 
Declaration 



Closes an open file. 

Close (var F) 



Remarks F is a file variable of any file type that was previously opened with Reset, 
Rewrite, or Append. The external file associated with F is completely 
updated and then closed, and its DOS file handle is freed for reuse. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

See also Append, Assign, Reset, Rewrite 

Example V ar F: file; 
begin 

Assign(F, 'AUTOEXEC.BAT'); { Open file } 

Reset (F, 1) ; 

Writelnf'File size = ', FileSize(F) ) ; 

Close (F); { Close file } 

end. 
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CloseGraph procedure 



Graph 



Function Shuts down the graphics system. 

Declaration CloseGraph 

Remarks CloseGraph restores the original screen mode before graphics was 

initialized and frees the memory allocated on the heap for the graphics 
scan buffer. CloseGraph also deallocates driver and font memory buffers if 
they were allocated by calls to GraphGetMem and Gra.phVreeM.em. 

Restrictions Must be in graphics mode. 

See also DetectGraph, GetGraphMode, InitGraph, RestoreCrtMode, SetGraphMode 

Example use s Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

Line(0, 0, GetMaxX, GetMaxY) ; 

Readln; 

CloseGraph; { Shut down graphics } 

end. 



ClrEol procedure 



Crt 



Function Clears all characters from the cursor position to the end of the line 
without moving the cursor. 

Declaration cirEoi 

Remarks All character positions are set to blanks with the currently defined text 

attributes. Thus, if TextBackground is not black, the column from the cursor 
to the right edge of the screen becomes the background color. 

This procedure is window-relative and will clear from the current cursor 
position (1, 1) to the right edge of the active window (60, 1). 

Window (1, 1, 60, 20); 
ClrEol; 

See also ClrScr, Window 
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ClrEol procedure 



Example uses crt; 
begin 

TextBackground(LightGray) ; 
ClrEol; 
end. 



{ Changes cleared columns to LightGray background } 



1 



ClrScr procedure 



Crt 



Function Clears the active window and places the cursor in the upper left-hand 
corner. 

Declaration cirscr 

Remarks All character positions are set to blanks with the currently defined text 
attributes. Thus, if TextBackground is not black, the entire screen becomes 
the background color. This also applies to characters cleared by ClrEol, 
InsLine, and DelLine, as well as empty lines created by scrolling. 

This procedure is window-relative and will clear a 60x20 rectangle 
beginning at (1, 1). 

Window (1, 1, 60, 20); 
ClrScr; 

See also ClrEol, Window 

Example uses Crt; 
begin 

TextBackground (LightGray) ; 

ClrScr; { Changes entire window to LightGray background } 

end. 



Conceit function 



Function Concatenates a sequence of strings. 

Declaration Concat(Sl [ , S2, ..., SN ]: String) 

Result type String 

Remarks Each parameter is a string-type expression. The result is the concatenation 
of all the string parameters. If the resulting string is longer than 255 
characters, it is truncated after the 255th character. Using the plus (+) 
operator returns the same results as using the Concat function: 

S := 'ABC + 'DEF'; 
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Concert function 



See also Copy, Delete, Insert, Length, Pos 
Example var 

S: String; 
begin 

S := ConcatCABC, 'DEF'); 
end. 



{ 'ABCDEF' } 



Copy function 



Function Returns a substring of a string. 

Declaration Copy(S: String; Index: Integer; Count: Integer) 

Result type String 

Remarks S is a string-type expression. Index and Count are integer-type expressions. 
Copy returns a string containing Count characters starting with the Indexth 
character in S. If Index is larger than the length of S, an empty string is 
returned. If Count specifies more characters than remain starting at the 
Indexth position, only the remainder of the string is returned. 

See also Concat, Delete, Insert, Length, Pos 

Example V ar S: String; 
begin 

S := 'ABCDEF'; 

S := Copy(S, 2, 3) { 'BCD' } 

end. 



Cos function 



Function Returns the cosine of the argument. 
Declaration cos(X: Real) 
Result type Real 

Remarks X is a real-type expression. The result is the cosine of X. X is assumed to 
represent an angle in radians. 

See also 



ArcTan, Sin 
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Cos function 



Example var R: Real; 
begin 

R := Cos (Pi); 
end. 



1 



CSeg function 



Function Returns the current value of the CS register. 

Declaration cseg 

Result type Word 

Remarks The result of type Word is the segment address of the code segment 
within which CSeg was called. 



See also DSeg, SSeg 



Dec procedure 



Function 

Declaration 

Remarks 



See also 
Example 



Decrements a variable. 

Dec (var X [ ; N: Longint ] ) 

X is an ordinal-type variable, and N is an integer-type expression. X is 
decremented by 1, or by N if N is specified; that is, DecOO corresponds to 
X := X - 1, and DeciX, N) corresponds to X := X - N. 

Dec generates optimized code and is especially useful in a tight loop. 

Inc, Pred, Succ 

var 

IntVar: Integer; 

Longint Var: Longint; 
begin 

Dec (IntVar); { IntVar := IntVar - 1 } 

Dec (LongintVar, 5); { LongintVar := LongintVar - 5 } 

end. 
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Delay procedure 



Delay procedure 



Crt 



Function Delays a specified number of milliseconds. 

Declaration Delay (Ms: Word) 

Remarks Ms specifies the number of milliseconds to wait. 

Delay is an approximation, so the delay period will not last exactly Ms 
milliseconds. 



Delete procedure 



Function Deletes a substring from a string. 

Declaration Delete (var S: String; Index: Integer; Count: Integer) 

Remarks S is a string-type variable. Index and Count are integer-type expressions. 
Delete deletes Count characters from S starting at the Indexth. position. If 
Index is larger than the length of S, no characters are deleted. If Count 
specifies more characters than remain starting at the Indexth. position, the 
remainder of the string is deleted. 

See also Concat, Copy, Insert, Length, Pos 



DelLine procedure 



Crt 



Function Deletes the line containing the cursor. 

Declaration DelLine 

Remarks The line containing the cursor is deleted, and all lines below are moved 
one line up (using the BIOS scroll routine). A new line is added at the 
bottom. 

All character positions are set to blanks with the currently defined text 
attributes. Thus, if TextBackground is not black, the new line becomes the 
background color. 

This procedure is window-relative and will delete the first line in the 
window, which is the tenth line on the screen. 

Window (1, 10, 60, 20); 
DelLine; 
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DelLine procedure 



See also InsLine, Window 



DetectGraph procedure 



Graph 



Function Checks the hardware and determines which graphics driver and mode to 
use. 

Declaration DetectGraph (var GraphDriver, GraphMode: Integer) 

Remarks Returns the detected driver and mode value that can be passed to 

InitGraph, which will then load the correct driver. If no graphics hardware 
was detected, the GraphDriver parameter and GraphResult returns a value 
of -2 (grNotDetected). 

The following constants are defined: 



{ Request autodetection } 



■ 



const 






Detect 


= 





CGA 


= 


1 


MCGA 


= 


2 


EGA 


= 


3 


EGA64 


= 


4 


EGAMono 


= 


5 


IBM8514 


= 


6 


HercMono 


= 


7 


ATT400 


= 


8 


VGA 


= 


9 



PC3270 = 10 

Unless instructed otherwise, InitGraph calls DetectGraph, finds and loads 
the correct driver, and initializes the graphics system. The only reason to 
call DetectGraph directly is to override the driver that DetectGraph recom- 
mends. The example that follows identifies the system as a 64K or 256K 
EGA, and loads the CGA driver instead. Note that when you pass 
InitGraph a GraphDriver other than Detect, you must also pass in a valid 
GraphMode for the driver requested. 

Restrictions You should not use DetectGraph (or Detect with InitGraph) with the IBM 
8514 unless you want the emulated VGA mode. 

See also CloseGraph, GraphResult, InitGraph 

Example uses Graph; 
var 

GraphDriver, GraphMode: Integer; 
begin 
DetectGraph (GraphDriver, GraphMode) ; 
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DetectGraph procedure 



if (GraphDriver = EGA) or 

(GraphDriver = EGA64) then 
begin 

GraphDriver := CGA; 

GraphMode := CGAHi; 
end; 

InitGraph (GraphDriver, GraphMode, " ) ; 
if GraphResult <> grOk then 

Halt(l); 
Line(0, 0, GetMaxX, GetMaxY) ; 
Readln; 
CloseGraph; 
end. 

DiskFree function Dos 

Function Returns the number of free bytes on a specified disk drive. 

Declaration DiskFree (Drive: Byte) 

Result type Longint 

Remarks A Drive of indicates the default drive, 1 indicates drive A, 2 indicates B, 
and so on. DiskFree returns -1 if the drive number is invalid. 

See also DiskSize, GetDir 

Example uses dos; 
begin 

Writeln (DiskFree (0) div 1024, ' Kbytes free '); 
end. 

DiskSize function Dos 

Function Returns the total size in bytes on a specified disk drive. 

Declaration DiskSize (Drive: Byte) 

Result type Longint 

Remarks A Drive of indicates the default drive, 1 indicates drive A, 2 indicates B, 
and so on. DiskSize returns -1 if the drive number is invalid. 

See also DiskFree, GetDir 
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DiskSize function 



Example uses n 0S ; 
begin 

Writeln (DiskSize (0) div 1024, ' Kbytes capacity' 
end. 



■ 



Dispose procedure 



Function Disposes a dynamic variable. 

Declaration Dispose (var P: Pointer [ , Destructor ] ) 

Remarks P is a pointer variable of any pointer type that was previously assigned by 
the New procedure or was assigned a meaningful value by an assignment 
statement. Dispose destroys the variable referenced by P and returns its 
memory region to the heap. After a call to Dispose, the value of P becomes 
undefined, and it is an error to subsequently reference P A . 

Dispose has been extended to allow a destructor call as a second parame- 
ter, for disposing a dynamic object type variable. In this case, P is a pointer 
variable pointing to an object type, and Destruct is a call to the destructor 
of that object type. 

Restrictions If P does not point to a memory region in the heap, a run-time error 
occurs. 

Dispose and FreeMem cannot be used interchangeably with Mark and 
Release unless certain rules are observed. For a complete discussion of this 
topic, see "The heap manager" in Chapter 16 in the Programmer's Guide. 

See also FreeMem, GetMem, Mark, New, Release 

Example type 

Strl8 = string [18]; 
var 

P: A Strl8; 
begin 

New(P); 

P A := 'Now you see it...'; 

Dispose (P); { Now you don't... } 

end. 
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DosExitCode function 



DosExitCode function 



Dos 



Function Returns the exit code of a subprocess. 

Declaration DosExitCode 

Result type Word 

Remarks The low byte is the code sent by the terminating process. The high byte is 
set to 

■ for normal termination 

■ 1 if terminated by Ctrl-C 

■ 2 if terminated due to a device error 

■ 3 if terminated by the Keep procedure 

See also Exec, Keep 



DosVersion function 



Dos 



Function Returns the DOS version number. 
Declaration DosVersion 
Result type Word 

Remarks DosVersion returns the DOS version number. The low byte of the result is 
the major version number, and the high byte is the minor version number. 
For example, DOS 3.20 returns 3 in the low byte, and 20 in the high byte. 

Example uses Dos; 
var 

Ver: Word; 
begin 

Ver := DosVersion; 

Writeln('This is DOS version ', Lo(Ver), '.', Hi (Ver)); 
end. 
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DrawPoly procedure 



Graph 



Function Draws the outline of a polygon using the current line style and color. 

Declaration DrawPoly (NumPoints: Word; var PolyPoints) 

Remarks PolyPoints is an untyped parameter that contains the coordinates of each 
intersection in the polygon. NumPoints specifies the number of coordi- 
nates in PolyPoints. A coordinate consists of two words, an X and a Y 
value. 

DrawPoly uses the current line style and color. Use SetWriteMode to 
determine whether the polygon is copied to or XOR'ed to the screen. 

Note that in order to draw a closed figure with N vertices, you must pass 
N + 1 coordinates to DrawPoly, where 

PolyPoints[N+l] = PolyPoints[l] 

In order to draw a triangle, for example, four coordinates must be passed 
to DrawPoly. 

Restrictions Must be in graphics mode. 

See also FillPoly, GetLineSettings, GraphResult, SetColor, SetLineStyle, SetWriteMode 

Example uses Graph; 
const 

Triangle: array [1.. 4] of PointType = ((X: 50; Y: 100), (X: 100; Y: 100), 
(X: 150; Y: 150), (X: 50; Y: 100)); 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

DrawPoly (SizeOf (Triangle) div SizeOf (PointType) , Triangle); { 4 } 

Readln; 

CloseGraph; 
end. 
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DSeg function 



DSeg function 



Function Returns the current value of the DS register. 

Declaration DSeg 

Result type Word 

Remarks The result of type Word is the segment address of the data segment. 

See also CSeg, SSeg 



Ellipse procedure 



Graph 



Function Draws an elliptical arc from start angle to end angle, using (X, Y) as the 
center point. 

Declaration Ellipse (X, Y: Integer; StAngle, EndAngle: Word; XRadius, YRadius: Word) 

Remarks Draws an elliptical arc using (X, Y) as a center point, and XRadius and 
YRadius as the horizontal and vertical axes. The ellipse travels from 
StAngle to EndAngle and is drawn in the current color. 

A start angle of and an end angle of 360 will draw a complete oval. The 
angles for Arc, Ellipse, and PieSlice are counterclockwise with degrees at 
3 o'clock, 90 degrees at 12 o'clock, and so on. Information about the last 
call to Ellipse can be retrieved with a call to GetArcCoords. 

Restrictions Must be in graphics mode. 

See also Arc, Circle, FillEllipse, GetArcCoords, GetAspectRatio, PieSlice, Sector, 
SetAspectRatio 

Example uses Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

Ellipse (100, 100, 0, 360, 30, 50); 

Ellipse (100, 100, 0, 180, 50, 30); 

Readln; 

CloseGraph; 
end. 
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EnvCount function 



Dos 



Function Returns the number of strings contained in the DOS environment. 
Declaration EnvCount 

Result type Integer 

Remarks EnvCount returns the number of strings contained in the DOS 

environment. Each environment string is of the form VAR=VALUE. The 
strings can be examined with the EnvStr function. 

For more information about the DOS environment, refer to your DOS 
manuals. 



1 



See also 


EnvStr, GetEnv 


Example 


uses Dos; 




var 




I: Integer; 




begin 




for I := 1 to EnvCount do 




Writeln (EnvStr (I)); 




end. 



EnvStr function 



Dos 



Function Returns a specified environment string. 

Declaration EnvStr( Index: Integer) 

Result type String 

Remarks EnvStr returns a specified string from the DOS environment. The string 
EnvStr returns is of the form VAR=VALUE. The index of the first string is 
one. If Index is less than one or greater than EnvCount, EnvStr returns an 
empty string. 

For more information about the DOS environment, refer to your DOS 
manuals. 



See also EnvCount, GetEnv 
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Eof function (text files) 



Function Returns the end-of-file status of a text file. 

Declaration Eof [ (var F: Text) ] 

Result type Boolean 

Remarks F, if specified, is a text-file variable. If F is omitted, the standard file 

variable Input is assumed. EofiF) returns True if the current file position is 
beyond the last character of the file or if the file contains no components; 
otherwise, EofiF) returns False. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

See also Eoln, SeekEof 

Example V ar 

F: Text; 

Ch: Char; 
begin 

{ Get file to read from command line } 

Assign (F, ParamStr (1) ) ; 

Reset (F) ; 

while not Eof (F) do 

begin 

Read(F, Ch) ; 

Write (Ch); { Dump text file ) 

end; 
end. 



Eof function (typed, untyped files) 



Function Returns the end-of-file status of a typed or untyped file. 
Declaration Eof (var f) 
Result type Boolean 

Remarks F is a file variable. EofiF) returns True if the current file position is beyond 
the last component of the file or if the file contains no components; 
otherwise, EofiF) returns False. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 
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Eoln function 



Function 

Declaration 

Result type 

Remarks 



See also 



Returns the end-of-line status of a file. 

Eoln [(var F: Text)] 

Boolean 

F, if specified, is a text-file variable. If F is omitted, the standard file 
variable Input is assumed. Eoln(F) returns True if the current file position 
is at an end-of-line marker or if EofiF) is True; otherwise, Eoln(F) returns 
False. 

When checking Eoln on standard input that has not been redirected, the 
following program will wait for a carriage return to be entered before 
returning from the call to Eoln: 

begin 

{ Tells program to wait for keyboard input } 

Writeln (Eoln) ; 
end. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Eof, SeekEoln 




Erase procedure 



Function Erases an external file. 

Declaration Erase (var F) 

Remarks F is a file variable of any file type. The external file associated with F is 
erased. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Restrictions Erase must never be used on an open file. 

See also Rename 

Example var 

F: file; 

Ch: Char; 
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Erase procedure 



begin 

{ Get file to delete from command line } 

Assign (F, ParamStr(l) ) ; 

{$1-} 

Reset (F) ; 

{$1+} 

if IOResult <> then 

WritelnC Cannot find ', ParamStr(l)) 
else 
begin 

Close (F); 

Write ('Erase ', ParamStr(l), '? '); 

Readln (Ch) ; 

if UpCase(ch) = 'V then 
Erase (F) ; 
end; 
end. 



Exec procedure 



Dos 



Function Executes a specified program with a specified command line. 

Declaration Exec (Path, CmdLine: String) 

Remarks The program name is given by the Path parameter, and the command line 
is given by CmdLine. To execute a DOS internal command, run 
COMMAND.COM; for instance, 

Exec ('\COMMAND. COM', ' /C DIR *.PAS'); 

The /C in front of the command is a requirement of COMMAND.COM 
(but not of other applications). Errors are reported in DosError, possible 
error codes are 2, 8, 10, and 11. The exit code of any child process is 
reported by the DosExitCode function. 

It is recommended that SzuapVectors be called just before and just after the 
call to Exec. SwapVectors swaps the contents of the SavelntXX pointers in 
the System unit with the current contents of the interrupt vectors. This 
ensures that the Exec' 6. process does not use any interrupt handlers 
installed by the current process, and vice versa. 

Exec does not change the memory allocation state before executing the 
program. Therefore, when compiling a program that uses Exec, be sure to 
reduce the "maximum" heap size; otherwise, there won't be enough 
memory {DosError = 8). 
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Exec procedure 



Restrictions Versions of the Novell Network system software earlier than 2.01 or 2.02 
do not support a DOS call used by Exec. If you are using the IDE to run a 
program that uses Exec, and you have early Novell system software, set 
Compile I Destination to Disk and run your program from DOS (you can 
use the File I DOS Shell command to do this). 



See also DosExitCode, SwapVectors 

Example {$ M $4000,0,0 } 
uses Dos; 



I 



{ 16K stack, no heap required or reserved } 



ProgramName, CmdLine: String; 
begin 

Write ('Program to Exec (include full path): '); 

Readln (ProgramName) ; 

Write ('Command line to pass to ', ProgramName, ': '); 

Readln (CmdLine) ; 

WritelnC About to Exec...'); 

SwapVectors; 

Exec (ProgramName, CmdLine); 

SwapVectors; 

WritelnC . . .back from Exec' ) ; 

if DosError <> then { Error? } 

WritelnC Dos error #', DosError) 

else 
Writelnf'Exec successful. Child process exit code = ', DosExitCode); 
end. 



Exit procedure 



Function Exits immediately from the current block. 

Declaration Exit 

Remarks When Exit is executed in a subroutine (procedure or function), it causes 
the subroutine to return. When it is executed in the statement part of a 
program, it causes the program to terminate. A call to Exit is analogous to 
a goto statement addressing a label just before the end of a block. 

See also Halt 

Example uses Crt; 

procedure WasteTime; 
begin 
repeat 

if KeyPressed then Exit; 
Write ('Xx') ; 
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Exit procedure 



until False; 
end; 

begin 

WasteTime; 
end. 



Exp function 



Function Returns the exponential of the argument. 

Declaration Exp(x: Real) 

Result type Real 

Remarks X is a real-type expression. The result is the exponential of X; that is, the 
value e raised to the power of X, where e is the base of the natural 
logarithms. 



See also Ln 



FExpand function 



Dos 



Function Expands a file name into a fully qualified file name. 

Declaration FExpand (Path: PathStr) 

Result type PathStr 

Remarks Expands the file name in Path into a fully qualified file name. The 

resulting name is converted to uppercase and consists of a drive letter, a 
colon, a root relative directory path, and a file name. Embedded V and '..' 
directory references are removed. 

The PathStr type is defined in the Dos unit as string[79]. 

Assuming that the current drive and directory is C:\SOURCE\PAS, the 
following FExpand calls would produce these values: 

FExpand ('test. pas') = 'C:\SOURCE\PAS\TEST.PAS' 

FExpand ('..\*.TPU') = 'C:\SOURCE\*.TPU' 

FExpand ('c:\bin\turbo.exe') = 'C:\BIN\TURBO.EXE' 

The FSplit procedure may be used to split the result of FExpand into a 
drive/ directory string, a file-name string, and an extension string. 

See also FindFirst, FindNext, FSplit 
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FilePos function 



Function Returns the current file position of a file. 
Declaration FilePos (var F) 
Result type Longint 

Remarks F is a file variable. If the current file position is at the beginning of the file, 
FilePosiF) returns 0. If the current file position is at the end of the file — that 
is, if EofiF) is True — FilePosiF) is equal to FileSize{F). 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Restrictions Cannot be used on a text file. File must be open. 

See also FileSize, Seek 

FileSize function 

Function Returns the current size of a file. 

Declaration FileSize(var F) 

Result type Longint 

Remarks F is a file variable. FileSize(F) returns the number of components in F. If 
the file is empty, FileSizeiF) returns 0. 

With {$!-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Restrictions Cannot be used on a text file. File must be open. 

See also FilePos 

Example var 

F: file of Byte; 
begin 

{ Get file name from command line } 
Assign (F, ParamStr(l) ) ; 
Reset (F) ; 

Writeln('File size in bytes: ', FileSize (F) ) ; 
Close (F) ; 
end. 



I 
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FillChar procedure 



Function Fills a specified number of contiguous bytes with a specified value. 

Declaration FillChar(var X; Count: Word; Value) 

Remarks X is a variable reference of any type. Count is an expression of type Word. 
Value is any ordinal-type expression. FillChar writes Count contiguous 
bytes of memory into Value, starting at the first byte occupied by X. No 
range-checking is performed, so be careful. 

Whenever possible, use the SizeOf function to specify the count parameter. 
When using FillChar on strings, remember to set the length byte after the 
fill. 



See also 


Move 


Example 


var 




S: string [80]; 




begin 




{ Set a string to all spaces } 




FillChar (S, SizeOf (S), ' '); 




S[0] := #80; 




end. 



{ Set length byte } 



FillEllipse procedure 



Graph 



Function 

Declaration 

Remarks 

Restrictions 
See also 

Example 



Draws a filled ellipse. 

FillEllipse (X, Y: Integer; XRadius, YRadius: Word) 

Draws a filled ellipse using (X, Y) as a center point, and XRadius and 
YRadius as the horizontal and vertical axes. The ellipse is filled with the 
current fill color and fill style, and is bordered with the current color. 

Must be in graphics mode. 

Arc, Circle, Ellipse, GetArcCoords, GetAspectRatio, PieSlice, Sector, 
SetAspectRatio 

uses 

Graph; 
const 

R = 30; 
var 

Driver, Mode: Integer; 
Xasp, Yasp: Word; 
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FillEllipse procedure 



begin 

Driver := Detect; 

InitGraph (Driver, Mode, "); 

if GraphResult < then 

Halt(l); 
{ Draw ellipse } 

FillEllipse (GetMaxX div 2, GetMaxY div 2, 50, 50); 
GetAspectRatio(Xasp, Yasp) ; 
{ Circular ellipse } 

FillEllipse (R, R, R, R * Longint (Xasp) div Yasp) ; 
Readln; 
CloseGraph; 
end. 



{ Put in graphics mode } 



I 



FillPoly procedure 



Graph 



Function Draws and fills a polygon, using the scan converter. 

Declaration FillPoly(NumPoints: Word; var PolyPoints) 

Remarks PolyPoints is an untyped parameter that contains the coordinates of each 
intersection in the polygon. NumPoints specifies the number of coordi- 
nates in PolyPoints. A coordinate consists of two words, an X and a Y 
value. 

FillPoly calculates all the horizontal intersections, and then fills the 
polygon using the current fill style and color defined by SetFillStyle or 
SetFillPattern. The outline of the polygon is drawn in the current line style 
and color as set by SetLineStyle. 

If an error occurs while filling the polygon, GraphResult returns a value of 
-6 (grNoScanMem). 

Restrictions Must be in graphics mode. 



See also 



Example 



DrawPoly, GetFillSettings, GetLineSettings, GraphResult, SetFillPattern, 
SetFillStyle, SetLineStyle 



uses Graph; 
const 

Triangle: array [1.. 3] of PointType = ( (X: 
(X: 100; Y: 100), (X: 150; Y: 150)); 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 



50; Y: 100), 
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FillPoly procedure 



if GraphResult <> grOk then 

Halt(l); 
FillPoly (SizeOf (Triangle) div SizeOf (PointType) , Triangle); 
Readln; 
CloseGraph; 
end. 



FindFirst procedure 



Dos 



Function Searches the specified (or current) directory for the first entry matching 
the specified file name and set of attributes. 

Declaration FindFirst (Path: String; Attr: Word; var S: SearchRec) 

Remarks Path is the directory mask (for example, * . *). The Attr parameter specifies 
the special files to include (in addition to all normal files). Here are the 
file attributes as they are declared in the Dos unit: 

const 

Readonly = $01 

Hidden = $02 

SysFile = $04 

VolumelD = $08 

Directory = $10 

Archive = $20 

AnyFile = $3F 

The result of the directory search is returned in the specified search 
record. SearchRec is declared in the Dos unit: 

type 
SearchRec = record 

Fill: array[1..21] of Byte; 

Attr: Byte; 

Time: Longint; 

Size: Longint; 

Name: string [12]; 
end; 

Errors are reported in DosError; possible error codes are 3 ("Directory Not 
Found") and 18 ("No More Files"). 



See also 



FExpand, FindNext 
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FindFirst procedure 



Example uses Dos; 
var 

Dirlnfo: SearchRec; 



begin 

FindFirst ('*. PAS', Archive, Dirlnfo); 

while DosError = do 

begin 

Writeln (Dirlnfo. Name); 

FindNext (Dirlnfo) ; 
end; 
end. 



{ Same as DIR *.PAS } 



1 



FindNext procedure 



Dos 



Function 

Declaration 
Remarks 

See also 
Example 



Returns the next entry that matches the name and attributes specified in a 
previous call to FindFirst. 

FindNext (var S: SearchRec) 

S must be the same one Passed to FindFirst (SearchRec is declared in Dos 
unit; see FindFirst). Errors are reported in DosError; the only possible error 
code is 18, which indicates no more files. 

FindFirst, FExpand 

See the example for FindFirst. 



FloodFill procedure 



Graph 



Function Fills a bounded region with the current fill pattern. 

Declaration FloodFill(X, Y: Integer; Border: Word) 

Remarks This procedure is called to fill an enclosed area on bitmap devices. (X, Y) 
is a seed within the enclosed area to be filled. The current fill pattern, as 
set by SetFillStyle or SetFillPattern, is used to flood the area bounded by 
Border color. If the seed point is within an enclosed area, then the inside 
will be filled. If the seed is outside the enclosed area, then the exterior will 
be filled. 

If an error occurs while flooding a region, GraphResult returns a value of 
-7 (grNoFloodMem). 
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FloodFill procedure 



Note that FloodFill stops after two blank lines have been output. This can 
occur with a sparse fill pattern and a small polygon. In the following 
program, the rectangle is not completely filled: 

program StopFill; 
uses Graph; 
var 

Driver, Mode: Integer; 
begin 

Driver := Detect; 

InitGraph (Driver, Mode, 'c:\bgi'); 

if GraphResult <> grOk then 
Halt(l); 

SetFillStyle (LtSlashFill, GetMaxColor) ; 

Rectangle (0, 0, 8, 20); 

FloodFill (1, 1, GetMaxColor); 

Readln; 

CloseGraph; 
end. 

In this case, using a denser fill pattern like SlashFill will completely fill the 
figure. 

Restrictions Use FillPoly instead of FloodFill whenever possible so that you can 

maintain code compatibility with future versions. Must be in graphics 
mode. This procedure is not available when using the IBM 8514 graphics 
driver (IBM8514.BGI). 

See also FillPoly, GraphResult, SetFillPattern, SetFillStyle 

Example uses Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

SetColor (GetMaxColor) ; 

Circle (50, 50, 20); 

FloodFill (50, 50, GetMaxColor); 

Readln; 

CloseGraph; 
end. 
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Flush procedure 



Function Flushes the buffer of a text file open for output. 

Declaration Flush (var F: Text) 

Remarks F is a text-file variable. 

When a text file has been opened for output using Rewrite or Append, a call 
to Flush will empty the file's buffer. This guarantees that all characters 
written to the file at that time have actually been written to the external 
file. Flush has no effect on files opened for input. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 



■ 



Frac function 



Function Returns the fractional part of the argument. 
Declaration Frac(X: Real) 

Result type Real 

Remarks X is a real-type expression. The result is the fractional part of X, that is, 
Frac(X) = X-Int(X). 



See also 


Int 




Example 


var 

R: Real; 
begin 






R := Frac (123. 456); 


{ 0.456 } 




R := Frac (-123. 456); 


{ -0.456 } 




end. 
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FreeMem procedure 



Function Disposes a dynamic variable of a given size. 

Declaration FreeMem (var P: Pointer; Size: Word) 

Remarks P is a pointer variable of any pointer type that was previously assigned by 
the GetMem procedure or was assigned a meaningful value by an assign- 
ment statement. Size is an expression of type Word, specifying the size in 
bytes of the dynamic variable to dispose; it must be exactly the number of 
bytes previously allocated to that variable by GetMem. FreeMem destroys 
the variable referenced by P and returns its memory region to the heap. If 
P does not point to a memory region in the heap, a run-time error occurs. 
After a call to FreeMem, the value of P becomes undefined, and it is an 
error to subsequently reference P A . 

Restrictions Dispose and FreeMem cannot be used interchangeably with Mark and 

Release unless certain rules are observed. For a complete discussion of this 
topic, see "The heap manager" in Chapter 16 of the Programmer's Guide. 



See also Dispose, GetMem, Mark, New, Release 



FSearch function 



Dos 



Function Searches for a hie in a list of directories. 

Declaration FSearch(Path: PathStr; DirList: String) 

Result type PathStr 

Remarks Searches for the file given by Path in the list of directories given by DirList. 
The directories in DirList must be separated by semicolons, just like the 
directories specified in a PATH command in DOS. The search always 
starts with the current directory of the current drive. The returned value is 
a concatenation of one of the directory paths and the file name, or an 
empty string if the file could not be located. 

The PathStr type is defined in the Dos unit as string[79]. 

To search the PATH used by DOS to locate executable files, call 
GetEnvCPATH') and pass the result to FSearch as the DirList parameter. 

The result oi'FSearch can be passed to FExpand to convert it into a fully 
qualified file name, that is, an uppercase file name that includes both a 
drive letter and a root-relative directory path. In addition, you can use 
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FSearch function 



FSplit to split the file name into a drive/directory string, a file-name 
string, and an extension string. 

See also FExpand, FSplit, GetEnv 

Example uses dos; 
var 

S: PathStr; 
begin 

S := FSearchCTURBO.EXE', GetEnv (' PATH' )) ; 
if S = " then 

WritelnCTURBO.EXE not found') 
else 
Writeln ('Found as ', FExpand (S)); 
end. 



I 



FSplit procedure 



Dos 



Function Splits a file name into its three components. 

Declaration FSplit(Path: PathStr; var Dir: DirStr; Var Name: NameStr; var Ext: ExtStr) 

Remarks Splits the file name specified by Path into its three components. Dir is set 
to the drive and directory path with any leading and trailing backslashes, 
Name is set to the file name, and Ext is set to the extension with a 
preceding dot. Each of the component strings may possibly be empty, if 
Path contains no such component. 

The PathStr, DirStr, NameStr, and ExtStr types are defined in the Dos unit 
as follows: 

type 

PathStr = string [79]; 
DirStr = string [67]; 
NameStr = string [8]; 
ExtStr = string [4]; 

FSplit never adds or removes characters when it splits the file name, and 
the concatenation of the resulting Dir, Name, and Ext will always equal the 
specified Path. 

See also FExpand, FindFirst, FindNext 

Example uses dos; 
var 

P: PathStr; 
D: DirStr; 
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FSplit procedure 



N: NameStr; 

E: ExtStr; 
begin 

Write ('Filename ( WORK. PAS ) : '); 

Readln (P) ; 

FSplit (P, D, N, E); 

if N = " then 
N := 'WORK'; 

if E = " then 
E := '.PAS'; 

P := D + N + E; 

Writeln ('Resulting name is ', P) ; 
end. 



GetArcCoords procedure 



Graph 



Function Allows the user to inquire about the coordinates of the last Arc command. 

Declaration GetArcCoords (var ArcCoords: ArcCoordsType) 

Remarks GetArcCoords returns a variable of type ArcCoordsType. ArcCoordsType is 
predeclared as follows: 

type 

ArcCoordsType = record 

X, Y: Integer; 

Xstart, Ystart: Integer; 

Xend, Yend: Integer; 
end; 

GetArcCoords returns a variable containing the center point (X, Y), the 
starting position (Xstart, Ystart), and the ending position (Xend, Yend) of 
the last Arc or Ellipse command. These values are useful if you need to 
connect a line to the end of an ellipse. 

Restrictions Must be in graphics mode. 

See also Arc, Circle, Ellipse, FillEllipse, PieSlice, PieSliceXY, Sector 

Example uses Graph; 
var 

Gd, Gm: Integer; 
ArcCoords: ArcCoordsType; 
begin 
Gd := Detect; 
InitGraph (Gd, Gm, "); 
if GraphResult <> grOk then 
Halt(l); 
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GetArcCoords procedure 



Arc(100, 100, 0, 270, 30); 
GetArcCoords (ArcCoords) ; 
with ArcCoords do 

Line(Xstart, Ystart, Xend, Yend) ; 
Readln; 
CloseGraph; 
end. 



GetAspectRatio procedure 



Graph 



Function Returns the effective resolution of the graphics screen from which the 
aspect ratio (Xasp-.Yasp) can be computed. 

Declaration GetAspectRatio (var Xasp, Yasp: Word) 

Remarks Each driver and graphics mode has an aspect ratio associated with it 
(maximum Y resolution divided by maximum X resolution). This ratio 
can be computed by making a call to GetAspectRatio and then dividing the 
Xasp parameter by the Yasp parameter. This ratio is used to make circles, 
arcs, and pie slices round. 

Restrictions Must be in graphics mode. 

See also Arc, Circle, Ellipse, GetMaxX, GetMaxY, PieSlice, SetAspectRatio 

Example uses Graph; 
var 

Gd, Gm: Integer; 
Xasp, Yasp: Word; 

XSideLength, YSideLength: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
GetAspectRatio (Xasp, Yasp) ; 
XSideLength := 20; 

{ Adjust Y length for aspect ratio } 

YSideLength := Round((Xasp / Yasp) * XSideLength); 

{ Draw a "square" rectangle on the screen } 
Rectangle (0, 0, XSideLength, YSideLength); 
Readln; 
CloseGraph; 
end. 
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GetBkColor function 



Graph 



Function Returns the index into the palette of the current background color. 
Declaration GetBkColor 

Result type Word 

Remarks Background colors can range from to 15, depending on the current 
graphics driver and current graphics mode. 

GetBkColor returns if the Oth palette entry is changed by a call to 
SetPalette or Set All? alette. 

Restrictions Must be in graphics mode. 

See also GetColor, GetPalette, InitGraph, SetAllPalette, SetBkColor, SetColor, SetPalette 

Example uses Crt, Graph; 
var 

Gd, Gm: Integer; 
Color: Word; 
Pal: PaletteType; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, " ) ; 

if GraphResult <> grOk then 

Halt(l); 
Randomize; 
GetPalette (Pal) ; 
if Pal. Size <> 1 then 
begin 
repeat 
Color := Succ (GetBkColor) ; 
if Color > Pal.Size-1 then 

Color := 0; 
SetBkColor (Color); 

LineTo (Random (GetMaxX) , Random (GetMaxY) ) ; 
until KeyPressed; 
end 
else 

Line(0, 0, GetMaxX, GetMaxY); 
Readln; 
CloseGraph; 
end. 



{ Cycle through colors } 
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GetCBreak procedure 



Dos 



Function Returns the state of Ctrl-Break checking in DOS. 

Declaration GetCBreak (var Break: Boolean) 

Remarks GetCBreak returns the state of Ctrl-Break checking in DOS. When off (False), 
DOS only checks for Ctrl-Break during I/O to console, printer, or communi- 
cation devices. When on (True), checks are made at every system call. 

See also SetCBreak 
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GetColor function 



Graph 



Function Returns the color value passed to the previous successful call to SetColor. 

Declaration GetColor 

Result type Word 

Remarks Drawing colors can range from to 15, depending on the current graphics 
driver and current graphics mode. 

Restrictions Must be in graphics mode. 

See also GetBkColor, GetPalette, InitGraph, Set AM? alette, SetColor, SetPalette 

Example U ses Graph; 
var 

Gd, Gm: Integer; 
Color: Word; 
Pal: PaletteType; 
- begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
Randomize; 
GetPalette (Pal); 
repeat 

Color := Succ (GetColor); 

if Color > Pal. Size - 1 then 
Color := 0; 

SetColor (Color) ; 
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GetColor function 



LineTo (Random (GetMaxX) , Random (GetMaxY) ) ; 
until KeyPressed; 
CloseGraph; 
end. 



GetDate procedure 



Dos 



Function Returns the current date set in the operating system. 

Declaration GetDate (var Year, Month, Day, DayofWeek: Word) 

Remarks Ranges of the values returned are Year 1980..2099, Month 1.12, Day 1..31, 
and DayOfWeek 0..6 (where corresponds to Sunday). 

See also GetTime, SetDate, SetTime 



GetDefaultPalette function 



Graph 



Function Returns the palette definition record. 

Declaration GetDefaultPalette (var Palette: PaletteType) 

Resulttype PaletteType 

Remarks GetDefaultPalette returns a PaletteType record, which contains the palette as 
the driver initialized it during InitGraph: 

const 

MaxColors =15; 
type 
PaletteType = record 

Size: Byte; 

Colors: array [0. .MaxColors] of Shortint; 
end; 

Restrictions Must be in graphics mode. 

See also InitGraph, GetPalette, Set AUP alette, SetPalette 

Example use s Crt, Graph; 
var 

Driver, Mode, I: Integer; 
MyPal, OldPal: PaletteType; 
begin 

Direct Video := False; 

Randomize; 

Driver := Detect; { Put in graphics mode } 
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{ Preserve old one } 
{ Duplicate and modify } 



GetDefaultPalette function 



InitGraph (Driver, Mode, " ) ; 
if GraphResult < then 

Halt(l); 
GetDefaultPalette (OldPal) ; 
MyPal := OldPal; 
{ Display something } 
for I := to MyPal.Size - 1 do 
begin 

SetColor(I); 

OutTextXY(10, I * 10, '...Press any key...'); 
end; 
repeat { Change palette until a key is pressed } 

with MyPal do 

Colors [Random (Size) ] := Random(Size + 1); 

SetAllPalette (MyPal) ; 
until KeyPressed; 

SetAllPalette (OldPal) ; { Restore original palette } 

ClearDevice; 

OutTextXY(10, 10, 'Press <Return>. ..') ; 
Readln; 
CloseGraph; 



1 



end. 



GetDir procedure 



Function Returns the current directory of a specified drive. 

Declaration GetDir (D: Byte; var S: String) 

Remarks D is an integer-type expression, and S is a string-type variable. The 

current directory of the drive specified by D is returned in S. D = indi- 
cates the current drive, 1 indicates drive A, 2 indicates drive B, and so on. 

GetDir performs no error-checking per se. If the drive specified by D is 
invalid, S returns ' V, as if it were the root directory of the invalid drive. 

See also ChDir, DiskFree, DiskSize, MkDir, RmDir 
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GetDriverName function 



Graph 



Function 

Declaration 

Result type 

Remarks 
Restrictions 

See also 

Example 



Returns a string containing the name of the current driver. 

GetDriverName 

String 

After a call to InitGraph, returns the name of the active driver. 

Must be in graphics mode. 

GetModeName, InitGraph 

uses Graph; 
var 

Driver, Mode: Integer; 
begin 

Driver := Detect; 

InitGraph (Driver, Mode, " ) ; 

if GraphResult < then 
Halt(l); 

OutText ('Using driver ' + GetDriverName); 

Readln; 

CloseGraph; 
end. 



{ Put in graphics mode } 



GetEnv function 



Dos 



Function Returns the value of a specified environment variable. 

Declaration GetEnv (EnvVar: String) 

Result type String 

Remarks GetEnv returns the value of a specified variable. The variable name can be 
in either uppercase or lowercase, but it must not include the equal sign (=) 
character. If the specified environment variable does not exist, GetEnv 
returns an empty string. 

For more information about the DOS environment, refer to your DOS 
manuals. 

See also EnvCount, EnvStr 

Example <$ M 8192,0,0} 

uses Dos; 
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GetEnv function 



var 

Command: string [79]; 
begin 

Write ('Enter DOS command: '); 

Readln (Command) ; 

if Command <> ' ' then 
Command := '/C ' + Command; 

SwapVectors; 

Exec (GetEnv ( ' COMSPEC ) , Command) ; 

SwapVectors; 

if DosError <> then 
WritelnC Could not execute C0MMAND.COM'); 
end. 
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GetFAttr procedure 



Dos 



Function Returns the attributes of a file. 

Declaration GetFAttr (var F; var Attr: Word); 

Remarks F must be a file variable (typed, untyped, or text file) that has been 

assigned but not opened. The attributes are examined by anding them 
with the file attribute masks defined as constants in the Dos unit: 

const 

Readonly = $01 

Hidden = $02 

SysFile = $04 

VolumelD = $08 

Directory = $10 

Archive = $20 

AnyFile = $3F 

Errors are reported in DosError; possible error codes are 

■ 3 (Invalid Path) 

■ 5 (File Access Denied) 

Restrictions F cannot be open. 

See also GetFTime, SetFAttr, SetFTime 

Example use s Dos; 
var 
F: file; 

Attr: Word; 
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GetFAttr procedure 



begin 

{ Get file name from command line } 
Assign (F, ParamStr (1) ) ; 
GetFAttr (F, Attr) ; 
Writeln (ParamStr (1)); 
if DosError <> then 

Writeln ('DOS error code = ', DosError) 
else 
begin 
Write ('Attribute = ', Attr); 

{ Determine file attribute type using flags in Dos unit } 
if Attr and Readonly <> then 

Writeln('Read only file'); 
if Attr and Hidden <> then 

Writeln ('Hidden file'); 
if Attr and SysFile <> then 

Writeln (' System file' ) ; 
if Attr and VolumelD <> then 

Writeln ('Volume ID'); 
if Attr and Directory <> then 

Writeln ('Directory name'); 
if Attr and Archive <> then 
Writeln ('Archive (normal file)'); 
end; { else } 
end. 



GetFillPattern procedure 



Graph 



Function Returns the last fill pattern set by a previous call to SetFillPattern. 

Declaration GetFillPattern (var FillPattern: FillPatternType); 

Remarks FillPatternType is declared in the Graph unit: 

type 

FillPatternType = array [1.. 8] of Byte; 

If no user call has been made to SetFillPattern, GetFillPattern returns an 
array filled with %FF. 

Restrictions Must be in graphics mode. 

See also GetFillSettings, SetFillPattern, SetFMStyle 
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GetFillSettings procedure 



Graph 



Function 

Declaration 
Remarks 



Restrictions 
See also 
Example 



Returns the last fill pattern and color set by a previous call to SetFillPattern 
or SetFillStyle. 

GetFillSettings (var Filllnfo: FillSettingsType) 

GetFillSettings returns a variable of type FillSettingsType. FillSettingsType is 
predeclared as follows: 

type 

FillSettingsType = record 

Pattern: Word; 

Color: Word; 
end; 

The Pattern field reports the current fill pattern selected. The Color field 
reports the current fill color selected. Both the fill pattern and color can be 
changed by calling the SetFillStyle or SetFillPattern procedure. If Pattern is 
equal to UserFill, use GetFillPattern to get the user-defined fill pattern that 
is selected. 

Must be in graphics mode. 

FillPoly, GetFillPattern, SetFillPattern, SetFillStyle 

uses Graph; 
var 

Gd, Gm: Integer; 

Filllnfo: FillSettingsType; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

GetFillSettings (Filllnfo) ; 

Bar(0, 0, 50, 50); 

SetFillStyle (XHatchFill, GetMaxColor) ; 

Bar (50, 0, 100, 50); 

with Filllnfo do 

SetFillStyle (Pattern, Color) ; 

Bar (100, 0, 150, 50); 

Readln; 

CloseGraph; 
end. 



1 



{ Save fill style and color } 
{ New style } 

{ Restore old fill style } 
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GetFTime procedure 



Dos 



Function Returns the date and time a file was last written. 

Declaration GetFTime (var F; var Time: Longint) 

Remarks F must be a file variable (typed, untyped, or text file) that has been 

assigned and opened. The time returned in the Time parameter may be 
unpacked through a call to UnpackTime. Errors are reported in DosError, 
the only possible error code is 6 (Invalid File Handle). 

Restrictions F must be open. 

See also PackTime, SetFAttr, SetFTime, UnpackTime 



GetGraphMode function 



Graph 



Function Returns the current graphics mode. 
Declaration GetGraphMode 

Result type Integer 

Remarks GetGraphMode returns the current graphics mode set by InitGraph or 

SetGraphMode. The Mode value is an integer from to 5, depending on the 
current driver. 

The following mode constants are defined: 



Graphics 
driver 


Constant 
name 


Value 


Column 
xrow 


Palette 


Pages 


CGA 


CGACO 
CGAC1 
CGAC2 
CGAC3 
CGAHi 



1 
2 
3 

4 


320x200 
320x200 
320x200 
320x200 
640x200 


CO 
CI 
C2 
C3 
2 color 


1 
1 
1 
1 
1 


MCGA 


MCGACO 

MCGACl 

MCGAC2 

MCGAC3 

MCGAMed 

MCGAHi 




1 
2 
3 

4 
5 


320x200 
320x200 
320x200 
320x200 
640x200 
640x480 


CO 

CI 

C2 

C3 
2 color 
2 color 


1 
1 
1 
1 
1 
1 


EGA 


EGALo 
EGAHi 



1 


640x200 
640x350 


16 color 
16 color 


4 
2 


EGA64 


EGA64Lo 
EGA64Hi 



1 


640x200 
640x350 


16 color 
4 color 


1 
1 
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Graphics 
driver 


Constant 
name 


Value 


Column 
xrow 


Palette 


Pages 


EGA-MONO 


EGAMonoHi 
EGAMonoHi 


3 
3 


640x350 
640x350 


2 color 
2 color 


1* 
2** 


HERC 


HercMonoHi 





720x348 


2 color 


2 


ATT400 


ATT400C0 

ATT400C1 

ATT400C2 

ATT400C3 

ATT400Med 

ATT400H1 



1 

2 
3 

4 
5 


320x200 
320x200 
320x200 
320x200 
640x200 
640x400 


CO 

CI 

C2 

C3 
2 color 
2 color 


1 
1 
1 
1 
1 
1 


VGA 


VGALo 

VGAMed 

VGAHi 



1 
2 


640x200 
640x350 
640x480 


16 color 
16 color 
16 color 


2 
2 
1 


PC3270 


PC3270Hi 





720x350 


2 color 


1 


IBM8514 
IBM8514 


IBM8514Lo 
IBM8514Hi 






640x480 
1024x768 


256 color 
256 color 


1 
1 


* 64K on EGAMono card 
" 256K on EGAMono card 











Restrictions Must be in graphics mode. 

See also ClearDevice, DetectGraph, InitGraph, RestoreCrtMode, SetGraphMode 

Example uses Graph; 
var 

Gd, Gm: Integer; 

Mode: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt (1) ; 

0utText('<ENTER> to leave graphics:'); 

Readln; 

RestoreCrtMode; 

Writeln('Now in text mode'); 

Write ('<ENTER> to enter graphics mode:'); 

Readln; 

SetGraphMode (GetGraphMode) ; 

OutTextXY(0, 0, 'Back in graphics mode'); 

OutTextXY(0, TextHeight ('H' ) , ' <ENTER> to quit : ' ) ; 

Readln; 

CloseGraph; 
end. 
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Get I mage procedure 



Getlmage procedure 



Graph 



Function Saves a bit image of the specified region into a buffer. 

Declaration GetImage(Xl, Yl, X2, Y2: Integer; var BitMap) 

Remarks XI, Yl, XI, and Y2 define a rectangular region on the screen. BitMap is an 
untyped parameter that must be greater than or equal to 6 plus the 
amount of area defined by the region. The first two words of BitMap store 
the width and height of the region. The third word is reserved. 

The remaining part of BitMap is used to save the bit image itself. Use the 
ImageSize function to determine the size requirements of BitMap. 

Restrictions Must be in graphics mode. The memory required to save the region must 
be less than 64K. 

See also ImageSize, Putlmage 

Example uses Graph; 
var 

Gd, Gm: Integer; 

P: Pointer; 

Size: Word; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

Bar(0, 0, GetMaxX, GetMaxY) ; 

Size := ImageSize (10, 20, 30, 40); 

GetMem(P, Size); 

Getlmage (10, 20, 30, 40, P A ); 

Readln; 

ClearDevice; 

Putlmage (100, 100, P A , NormalPut) ; 

Readln; 

CloseGraph; 
end. 



{ Allocate memory on heap } 
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GetlntVec procedure 



Dos 



Function Returns the address stored in a specified interrupt vector. 

Declaration GetIntVec(IntNo: Byte; var Vector: Pointer) 

Remarks IntNo specifies the interrupt vector number (0..255), and the address is 
returned in Vector. 

See also SetlntVec 
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GetLineSettings procedure 



Graph 



Function 

Declaration 
Remarks 



Restrictions 
See also 
Example 



Returns the current line style, line pattern, and line thickness as set by 
SetLineStyle. 

GetLineSettings (var Linelnfo: LineSettingsType) 
The following type and constants are defined: 

type 

LineSettingsType = record 

LineStyle: Word; 

Pattern: Word; 

Thickness: Word; 
end; 
const 

{ Line styles } 
SolidLn = 0; 
DottedLn = 1; 
CenterLn = 2; 
DashedLn = 3; 
UserBitLn = 4; 
{ Line widths } 
NormWidth = 1; 
ThickWidth = 3; 

Must be in graphics mode. 

DraivPoly, SetLineStyle 

uses Graph; 
var 

Gd, Gm: Integer; 

OldStyle: LineSettingsType; 



{ User-defined line style } 
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GetLineSettings procedure 



begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
Line(0, 0, 100, 0); 
GetLineSettings (OldStyle) ; 
SetLineStyle (DottedLn, 0, ThickWidth) ; 
Line(0, 10, 100, 10); 
with OldStyle do 

SetLineStyle (LineStyle, Pattern, Thickness); 
Line(0, 20, 100, 20); 
Readln; 
CloseGraph; 
end. 



{ New style } 
{ Restore old line style } 



GetMaxColor function 



Graph 



Function Returns the highest color that can be passed to the SetColor procedure. 

Declaration GetMaxColor 

Result type Word 

Remarks As an example, on a 256K EGA, GetMaxColor will always return 15, which 
means that any call to SetColor with a value from 0..15 is valid. On a CGA 
in high-resolution mode or on a Hercules monochrome adapter, 
GetMaxColor returns a value of 1 because these adapters only support 
draw colors of or 1. 

Restrictions Must be in graphics mode. 

See also SetColor 



GetMaxMode function 



Graph 



Function Returns the maximum mode number for the currently loaded driver. 
Declaration GetMaxMode 

Result type Word 

Remarks GetMaxMode lets you find out the maximum mode number for the current 
driver, directly from the driver. (Formerly, GetModeRange was the only way 
you could get this number; GetModeRange is still supported, but only for 
the Borland drivers.) 
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GetMaxMode function 



The value returned by GetMaxMode is the maximum value that may be 
passed to SetGraphMode. Every driver supports modes 0.. GetMaxMode. 

Restrictions Must be in graphics mode. 

See also GetModeRange, SetGraphMode 

Example uses Graph; 
var 

Driver, Mode: Integer; 

I: Integer; 
begin 

Driver := Detect; 

InitGraph (Driver, Mode, "); 

if GraphResult < then 
Halt(l); 

for I := to GetMaxMode do 
OutTextXY(10, 10 * Succ(I), GetModeName(I) ) ; 

Readln; 

CloseGraph; 
end. 



{ Put in graphics mode } 



{ Display all mode names } 



I 



GetMaxX function 



Graph 



Function Returns the rightmost column (x resolution) of the current graphics driver 
and mode. 

Declaration GetMaxx 

Result type Integer 

Remarks Returns the maximum X value for the current graphics driver and mode. 
On a CGA in 320x200 mode; for example, GetMaxX returns 319. 

GetMaxX and GetMaxY are invaluable for centering, determining the 
boundaries of a region on the screen, and so on. 

Restrictions Must be in graphics mode. 

See also GetMaxY, GetX, GetY, MoveTo 

Example uses Graph; 
var 

Gd, Gm: Integer; 
begin 
Gd := Detect; 
InitGraph (Gd, Gm, "); 
if GraphResult <> grOk then 
Halt(l); 



Chapter 1, The run-time library 



57 



GetMaxX function 



Rectangle (0, 0, GetMaxX, GetMaxY); 
Readln; 
CloseGraph; 
end. 



{ Draw a full-screen box } 



GetMaxY function 



Graph 



Function Returns the bottommost row (y resolution) of the current graphics driver 
and mode. 

Declaration GetMaxY 

Result type Integer 

Remarks Returns the maximum y value for the current graphics driver and mode. 
On a CGA in 320x200 mode; for example, GetMaxY returns 199. 

GetMaxX and GetMaxY are invaluable for centering, determining the 
boundaries of a region on the screen, and so on. 

Restrictions Must be in graphics mode. 

See also GetMaxX, GetX, GetY, MoveTo 

Example uses Grap h; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

Rectangle (0, 0, GetMaxX, GetMaxY); { Draw a full-screen box } 

Readln; 

CloseGraph; 
end. 



GetMem procedure 



Function Creates a new dynamic variable of the specified size, and puts the address 
of the block in a pointer variable. 

Declaration GetMem (var P: Pointer; Size: Word) 
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GetMem procedure 



Remarks P is a pointer variable of any pointer type. Size is an expression of type 

Word specifying the size in bytes of the dynamic variable to allocate. The 
newly created variable can be referenced as P A . 

If there isn't enough free space in the heap to allocate the new variable, a 
run-time error occurs. (It is possible to avoid a run-time error; see "The 
HeapError variable" in Chapter 16 of the Programmer's Guide.) 

Restrictions The largest block that can be allocated on the heap at one time is 65,521 

bytes (64K-$F). If the heap is not fragmented, for example at the beginning 
of a program, successive calls to GetMem returns neighboring blocks of 
memory. 

See also Dispose, FreeMem, Mark, New, Release 
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GetModeName function 



Graph 



Function Returns a string containing the name of the specified graphics mode. 

Declaration GetModeName (ModeNumber: Integer) 

Result type String 

Remarks The mode names are embedded in each driver. The return values (320x200 
CGA PI, 640x200 CGA, etc.) are useful for building menus, display status, 
and so forth. 

Restrictions Must be in graphics mode. 

See also GetDriverName, GetMaxMode, GetModeRange 

Example US6S Graph; 
var 

Driver, Mode: Integer; 

I: Integer; 
begin 

Driver := Detect; 

InitGraph (Driver, Mode, " ) ; 

if GraphResult < then 
Halt(l); 

for I := to GetMaxMode do 
OutTextXY(10, 10 * Succ(I), GetModeName (I) ) ; 

Readln; 

CloseGraph; 
end. 



{ Put in graphics mode } 



{ Display all mode names } 
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GetModeRange procedure 



Graph 



Function Returns the lowest and highest valid graphics mode for a given driver. 

Declaration GetModeRange (GraphDriver: Integer; var LoMode, HiMode: Integer); 

Remarks The output from the following program will be Lowest - and Highest = 1: 

uses Graph; 
var 

Lowest, Highest: Integer; 
begin 

GetModeRange (EGA64, Lowest, Highest); 

Write ('Lowest = ', Lowest); 

Write (' Highest = ', Highest); 
end. 

If the value of GraphDriver is invalid, the return parameters are set to -1. 

See also DetectGraph, GetGraphMode, InitGraph, SetGraphMode 



GetPalette procedure 



Graph 



Function Returns the current palette and its size. 

Declaration GetPalette (var Palette: PaletteType) 

Remarks Returns the current palette and its size in a variable of type PaletteType. 
PaletteType is defined as follows: 

const 

MaxColors =15; 
type 
PaletteType = record 

Size: Byte; 

Colors: array [0. .MaxColors] of Shortint; 
end; 

The size field reports the number of colors in the palette for the current 
driver in the current mode. Colors contains the actual colors O.Size - 1. 

Restrictions Must be in graphics mode, and can only be used with EGA, EGA 64, or 
VGA (not the IBM 8514 or the VGA in 256-color mode). 

See also GetDefaultPalette, GetPaletteSize, Set AUP alette, SetPalette 
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GetPalette procedure 



Example uses Graph; 
var 

Gd, Gm: Integer; 
Color: Word; 
Palette: PaletteType; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
GetPalette (Palette); 
if Palette. Size <> 1 then 

for Color := to Pred(Palette.Size) do 

begin 

SetColor (Color); 

Line(0, Color * 5, 100, Color * 5) ; 

end 
else 

Line(0, 0, 100, 0) ; 
Readln; 
CloseGraph; 
end. 




GetPaletteSize function 



Graph 



Function Returns the the size of the palette color lookup table. 

Declaration GetPaletteSize 

Result type Integer 

Remarks GetPaletteSize reports how many palette entries can be set for the current 
graphics mode; for example, the EGA in color mode returns a value of 16. 

Restrictions Must be in graphics mode. 

See also GetDefaultPalette, GetMaxColor, GetPalette, SetPalette 
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GetPixel function 



GetPixel function 



Graph 



Function 


Gets the pixel value at X, Y. 


Declaration 


GetPixel (X, Y: Integer) 


Result type 


Word 


Remarks 


Gets the pixel color at (X, Y). 


Restrictions 


Must be in graphics mode. 


See also 


Getlmage, Putlmage, PutPixel, SetWriteMode 


Example 


uses Graph; 




var 




Gd, Gm: Integer; 




PixelColor: Word; 




begin 




Gd := Detect; 




InitGraph(Gd, Gm, "); 




if GraphResult <> grOk then 




Halt(l); 




PixelColor := GetPixel (10, 10); 




if PixelColor = then 




PutPixel (10, 10, GetMaxColor) ; 




Readln; 




CloseGraph; 




end. 



GetTextSettings procedure 



Graph 



Function Returns the current text font, direction, size, and justification as set by 
SetTextStyle and SetText Justify. 

Declaration GetTextSettings (var Textlnfo: TextSettingsType) 

Remarks The following type and constants are defined: 

type 

TextSettingsType = record 

Font: Word; 

Direction: Word; 

CharSize: Word; 

Horiz: Word; 

Vert: Word; 
end; 
const 
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GetTextSettings procedure 



DefaultFont = 

TriplexFont = 1 

SmallFont = 2 

SansSerifFont = 3 

GothicFont = 4 

HorizDir = 

VertDir = 1 



{ 8x8 bit-mapped font } 
{ Stroked fonts } 



{ Left to right } 
{ Bottom to top } 



Restrictions Must be in graphics mode. 

See also InitGraph, SetTextJustify, SetTextStyle, TextHeight, TextWidth 

Example uses Graph; 
var 

Gd, Gm: Integer; 
OldStyle: TextSettingsType; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
GetTextSettings (OldStyle) ; 
OutTextXY(0, 0, 'Old text style'); 
SetTextJustify (LeftText, CenterText) ; 
SetTextStyle (TriplexFont, VertDir, 4); 
OutTextXY (GetMaxX div 2, GetMaxY div 2, 'New Style'); 
with OldStyle do 
begin { Restore old text style } 

SetTextJustify (Horiz, Vert); 

SetTextStyle (Font, Direction, CharSize) ; 
end; 

OutTextXY(0, TextHeight ('H' ) , 'Old style again') ; 
Readln; 
CloseGraph; 
end. 



I 



GetTime procedure 



Dos 



Function Returns the current time set in the operating system. 

Declaration GetTime (var Hour, Minute, Second, SeclOO: Word) 

Remarks Ranges of the values returned are Hour 0..23, Minute 0..59, Second 0..59, 
and SeclOO (hundredths of seconds) 0..99. 



See also 



GetDate, SetDate, SetTime, UnpackTime 
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GetVerify procedure 



GetVerify procedure 



Dos 



Function Returns the state of the verify flag in DOS. 

Declaration GetVerify (var Verify: Boolean) 

Remarks GetVerify returns the state of the verify flag in DOS. When off (False), disk 
writes are not verified. When on (True), all disk writes are verified to 
ensure proper writing. 

See also SetVerify 



GetViewSettings procedure 



Graph 



Function Returns the current viewport and clipping parameters, as set by 
SetViewPort. 

Declaration GetViewSettings (var ViewPort: ViewPortType) 

Remarks GetViewSettings returns a variable of type ViewPortType. 
ViewPortType is predeclared as follows: 

type 

ViewPortType = record 

XI, Yl, X2, Y2: Integer; 

Clip: Boolean; 
end; 

The points (XI, Yl) and (X2, Y2) are the dimensions of the active viewport 
and are given in absolute screen coordinates. Clip is a Boolean variable 
that controls whether clipping is active. 

Restrictions Must be in graphics mode. 

See also ClearViewPort, SetViewPort 

Example use s Graph; 
var 

Gd, Gm: Integer; 
ViewPort: ViewPortType; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
GetViewSettings (ViewPort) ; 
with ViewPort do 
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GetViewSettings procedure 



begin 

Rectangle (0, 0, X2 - XI, Y2 - Yl), 
if Clip then 

OutTextC Clipping is active.') 
else 
OutText('No clipping today.'); 
end; 
Readln; 
CloseGraph; 
end. 



GetX function 



Graph 



i 



Function Returns the X coordinate of the current position (CP). 

Declaration Getx 

Result type Integer 

Remarks GetX is viewport-relative. In the following example, 

1. SetViewPort(0, 0, GetMaxX, GetMaxY, True); 

2. MoveTo(5, 5); 

3. SetViewPort(10, 10, 100, 100, True); 

4. MoveTo(5, 5) ; 

Line 1 moves CP to absolute (0, 0), and GetX would also return a value of 
0. Line 2 moves CP to absolute (5, 5), and GetX would also return a value 
of 5. Line 3 moves CP to absolute (10, 10), but GetX would return a value 
of 0. Line 4 moves CP to absolute (15, 15), but GetX would return a value 
of 5. 

Restrictions Must be in graphics mode. 

See also GetViewSettings, GetY, InitGraph, MoveTo, SetViewPort 

Example use s Graph; 
var 

Gd, Gm: Integer; 
X, Y: Integer; 
begin 
Gd := Detect; 
InitGraph (Gd, Gm, "); 
if GraphResult <> grOk then 

Halt(l); 
OutText ( ' Starting here . ' ) ; 
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GetX function 



X := GetX; 
Y := GetY; 

OutTextXY(20, 10, 'Now over here. ..') ; 
OutTextXY (X, Y, 'Now back over here.'); 
Readln; 
CloseGraph; 
end. 



GetY function 



Graph 



Function Returns the Y coordinate of the current position (CP). 

Declaration GetY 

Result type Integer 

Remarks GetY is viewport-relative. In the following example, 

1. SetViewPort(0, 0, GetMaxX, GetMaxY, True); 

2. MoveTo(5, 5); 

3. SetViewPort(10, 10, 100, 100, True); 

4. MoveTo(5, 5); 

Line 1 moves CP to absolute (0, 0), and GetY would also return a value of 
0. Line 2 moves CP to absolute (5, 5), and GetY would also return a value 
of 5. Line 3 moves CP to absolute (10, 10), but GetY would return a value 
of 0. Line 4 moves CP to absolute (15, 15), but GetY would return a value 
of 5. 

Restrictions Must be in graphics mode. 

See also GetViewSettings, GetX, InitGraph, MoveTo, SetViewPort 

Example uses Graph; 
var 

Gd, Gm: Integer; 
X, Y: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
OutTextC Starting here. '); 
X := GetX; 
Y := GetY; 
OutTextXY(20, 10, 'Now over here...'); 
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GetY function 



OutTextXY (X, Y, 'Now back over here.'); 
Readln; 
CloseGraph; 
end. 



GotoXY procedure 



Crt 



Function Positions the cursor. 

Declaration GotoXY(X, Y: Byte) 

Remarks The cursor is moved to the position within the current window specified 
by X and Y (X is the column, Y is the row). The upper left corner is (1, 1). 

This procedure is window-relative and will move the cursor to the upper 
left corner of the active window (absolute coordinates (1, 10)): 

Windowd, 10, 60, 20); 
GotoXY (1, 1); 

Restrictions If the coordinates are in any way invalid, the call to GotoXY is ignored. 

See also WhereX, WhereY, Window 
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GraphDefaults procedure 



Graph 



Function Resets the graphics settings. 

Declaration GraphDefaults 

Remarks Homes the current pointer (CP) and resets the graphics system to the 
default values for 

■ viewport 

■ palette 

■ draw and background colors 

■ line style and line pattern 

■ fill style, fill color, and fill pattern 

■ active font, text style, text justification, and user Char size 
Restrictions Must be in graphics mode. 

See also InitGraph 
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GraphErrorMsg function 



Graph 



Function Returns an error message string for the specified ErrorCode. 

Declaration GraphErrorMsg (ErrorCode: Integer) 

Result type String 

Remarks This function returns a string containing an error message that 

corresponds with the error codes in the graphics system. This makes it 
easy for a user program to display a descriptive error message ("Device 
driver not found" instead of "error code -3"). 

See also DetectGraph, GraphResult, InitGraph 

Example uses Graph; 
var 

GraphDriver, GraphMode: Integer; 
ErrorCode: Integer; 
begin 

GraphDriver := Detect; 

InitGraph (GraphDriver, GraphMode, " ) ; 

ErrorCode := GraphResult; 

if ErrorCode <> grOk then 

begin 

WritelnC Graphics error: ', 

Readln; 

Halt(l); 
end; 

Line(0, 0, GetMaxX, GetMaxY) ; 
Readln; 
CloseGraph; 
end. 



GraphErrorMsg (ErrorCode) ) ; 



GraphResult function 



Graph 



Function Returns an error code for the last graphics operation. 
Declaration GraphResult 

Result type Integer 

Remarks Returns an error code for the last graphics operation. The following error 
return codes are defined: 
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GraphResult function 



See also 
Example 



Error 


Graphics error 


Corresponding 


code 


constant 


error message string 





grOk 


No error 


-1 


grNoInitGraph 


(BGI) graphics not installed (use InitGraph) 


-2 


grNotDetected 


Graphics hardware not detected 


-3 


grFileNotFound 


Device driver file not found 


-4 


grlnvalidDriver 


Invalid device driver file 


-5 


grNoLoadMetn 


Not enough memory to load driver 


-6 


grNoScanMem 


Out of memory in scan fill 


-7 


grNoFloodMem 


Out of memory in flood fill 


-8 


grFontNotFound 


Font file not found 


-9 


grNoFontMem 


Not enough memory to load font 


-10 


grlnvalidMode 


Invalid graphics mode for selected driver 


-11 


grError 


Graphics error 


-12 


grIOerror 


Graphics I/O error 


-13 


grlnvalidFont 


Invalid font file 


-14 


grlnvalidFontNum 


Invalid font number 



1 



The following routines set GraphResult: 

Bar GetGraphMode 

ImageSize 



SetAllPalette 
Bar3D ImageSize SetFillPattern 

ClearViewPort InitGraph SetFillStyle 

CloseGraph InstallUserDriver SetGraphBufSize 

DetectGraph InstallUserFont SetGraphMode 

DrawPoty PieSHce SetLineStyle 

FillPoly RegisterBGIdriver SetPalette 

FloodFill RegisterBGIfont SetTextJustify 

SetTextStyle 

Note that GraphResult is reset to zero after it has been called (similar to 
IOResult). Therefore, the user should store the value of GraphResult into a 
temporary variable and then test it. 

A string function, GraphErrorMsg, is provided to return a string that 
corresponds with each error code. 

GraphErrorMsg 

uses Graph; 
var 

ErrorCode: Integer; 
GrDriver, GrMode: Integer; 
begin 

GrDriver := Detect; 

InitGraph (GrDriver, GrMode, " ) ; 

ErrorCode := GraphResult; 

if ErrorCode <> grOk then 

begin 



{ Check for errors } 
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GraphResult function 



WritelnC Graphics error:'); 

Writeln (GraphErrorMsg (ErrorCode) ) ; 

Writeln ('Program aborted...'); 

Halt(l); 
end; 

{ Do some graphics ... } 
ClearDevice; 

Rectangle (0, 0, GetMaxX, GetMaxY); 
Readln; 
CloseGraph; 
end. 



Halt procedure 



Function Stops program execution and returns to the operating system. 

Declaration Halt [ ( ExitCode: Word ) ] 

Remarks ExitCode is an optional expression of type Word that specifies the exit code 
of the program. Halt without a parameter corresponds to Halt(O). The exit 
code can be examined by a parent process using the DosExitCode function 
in the Dos unit or through an ERRORLEVEL test in a DOS batch file. 

Note that Halt will initiate execution of any unit Exit procedures (see 
Chapter 18 in the Programmer's Guide). 



See also Exit, RunError 



Hi function 



Function Returns the high-order byte of the argument. 

Declaration Hi (x) 

Result type Byte 

Remarks X is an expression of type Integer or Word. Hi returns the high-order byte 
of X as an unsigned value. 

See also Lo, Swap 

Example var W: Wor d ; 
begin 

W := Hi ($1234); { $12 } 
end. 
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HighVideo procedure 



Crt 



Function Selects high-intensity characters. 

Declaration HighVideo 

Remarks There is a Byte variable in Crt — TextAttr — that is used to hold the current 
video attribute. HighVideo sets the high intensity bit of TextAttfs fore- 
ground color, thus mapping colors 0-7 onto colors 8-15. 

See also LowVideo, NormVideo, TextBackground, TextColor 

Example use s crt; 
begin 

TextAttr := LightGray; 

HighVideo; { Color is now white } 

end. 



B 



ImageSize function 



Graph 



Function Returns the number of bytes required to store a rectangular region of the 
screen. 

Declaration ImageSize(Xl, Yl, X2, Y2: Integer) 

Result type Word 

Remarks XI, Yl, XI, and Y2 define a rectangular region on the screen. ImageSize 
determines the number of bytes necessary for Gethnage to save the 
specified region of the screen. The image size includes space for three 
words. The first stores the width of the region, the second stores the 
height, and the third is reserved. 

If the memory required to save the region is greater than or equal to 64K, 
a value of is returned and GraphResult returns -11 (grError). 



Restrictions 


Must be in graphics mode. 


See also 


Gethnage, Putlmage 


Example 


uses Graph; 




var 




Gd, Gm: Integer; 




P: Pointer; 




Size: Word; 
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ImageSize function 



begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
Bar(0 ; 0, GetMaxX, GetMaxY) ; 
Size := ImageSize (10, 20, 30, 40); 
GetMem(P, Size); 
Getlmage(10, 20, 30, 40, P A ); 
Readln; 
ClearDevice; 

Put Image (100, 100, P\ NormalPut) ; 
Readln; 
CloseGraph; 
end. 



Allocate memory on heap } 



Inc procedure 



Function Increments a variable. 

Declaration Inc(var X [ ; N: Longint ] ) 

Remarks X is an ordinal-type variable, and N is an integer-type expression. X is 

incremented by 1, or by N if N is specified; that is, Inc(X) corresponds to X 
:= X + 1, and InciX, N) corresponds to X := X + N. 

Inc generates optimized code and is especially useful for use in tight 
loops. 



See also 


Dec, Pred, Succ 


Example 


var 




IntVar: Integer; 




Longint Var: Longint; 




begin 




Inc (IntVar); 




Inc (Longint Var, 5); 




end. 



{ IntVar := IntVar + 1 } 
{ Longint Var := Longint Var + 5 } 
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InitGraph procedure 



Graph 



Function Initializes the graphics system and puts the hardware into graphics mode. 

Declaration InitGraph (var GraphDriver: Integer; var GraphMode: Integer; PathToDriver: String) 

Remarks Both GraphDriver and GraphMode are var parameters. 

If GraphDriver is equal to Detectiff), a call is made to any user-defined 
autodetect routines (see InstallUserDriver) and then DetectGraph. If 
graphics hardware is detected, the appropriate graphics driver is 
initialized, and a graphics mode is selected. 

If GraphDriver is not equal to 0, the value of GraphDriver is assumed to be 
a driver number; that driver is selected, and the system is put into the 
mode specified by GraphMode. If you override autodetection in this 
manner, you must supply a valid GraphMode parameter for the driver 
requested. 

PathToDriver specifies the directory path where the graphics drivers can 
be found. If PathToDriver is null, the driver files must be in the current 
directory. 

Normally, InitGraph loads a graphics driver by allocating memory for the 
driver (through GraphGetMem), then loads the appropriate .BGI file from 
disk. As an alternative to this dynamic loading scheme, you can link a 
graphics driver file (or several of them) directly into your executable 
program file. You do this by first converting the .BGI file to an .OBJ file 
(using the BINOBJ utility), then placing calls to RegisterBGIdriver in your 
source code (before the call to InitGraph) to register the graphics driver(s). 
When you build your program, you must link the .OBJ files for the 
registered drivers. You can also load a BGI driver onto the heap and then 
register it using RegisterBGIdriver. 

If memory for the graphics driver is allocated on the heap using 
GraphGetMem, that memory is released when a call is made to CloseGraph. 

After calling InitGraph, GraphDriver will be set to the current graphics 
driver, and GraphMode will be set to the current graphics mode. 

If an error occurred, both GraphDriver and GraphResult (a function) returns 
one of the following values: 



M 



-2 Cannot detect a graphics card 

-3 Cannot find driver file 

-4 Invalid driver 
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InitGraph procedure 



-5 Insufficient memory to load driver 

-10 Invalid graphics mode for selected driver 

InitGraph resets all graphics settings to their defaults (current pointer, 
palette, color, viewport, etc.). 

You can use InstallDriver to install a vendor-supplied graphics driver (see 
InstallUserDriver for more information). 

Several useful constants are defined for each graphics driver supported: 



Error 


Graphics error 


Corresponding 


code 


constant 


error message string 





grOk 


No error 


-1 


grNoInitGraph 


(BGI) graphics not installed (use InitGraph) 


-2 


grNotDetected 


Graphics hardware not detected 


-3 


grFileNotFound 


Device driver file not found 


-4 


grlnvalidDriver 


Invalid device driver file 


-5 


grNoLoadMem 


Not enough memory to load driver 


-6 


grNoScanMem 


Out of memory in scan fill 


-7 


grNoFloodMem 


Out of memory in flood fill 


-8 


grFontNotFound 


Font file not found 


-9 


grNoFontMem 


Not enough memory to load font 


-10 


grlnvalidMode 


Invalid graphics mode for selected driver 


-11 


grError 


Graphics error 


-12 


grIOerror 


Graphics I/O error 


-13 


grlnvalidFont 


Invalid font file 


-14 


grlnvalidFontNum 


Invalid font number 



Restrictions Must be in graphics mode. If you use the Borland Graphics Interface (BGI) 
on a Zenith Z-449 card, Turbo Pascal's autodetection code will always 
select the 640x480 enhanced EGA mode. If this mode isn't compatible 
with your monitor, select a different mode in the InitGraph call. Also, 
Turbo Pascal cannot autodetect the IBM 8514 graphics card (the 
autodetection logic recognizes it as VGA). Therefore, to use the IBM 8514 
card, the GraphDriver variable must be assigned the value IBM8514 (which 
is defined in the Graph unit) when InitGraph is called. You should not use 
DetectGraph (or Detect with InitGraph) with the IBM 8514 unless you want 
the emulated VGA mode. 

See also CloseGraph, DetectGraph, GraphDefaults, GraphResult, InstallUserDriver, 
RegisterBGIdriver, RegisterBGIfont, RestoreCrtMode, SetGraphBufSize, 
SetGraphMode 

Example uses Graph; 
var 

grDriver: Integer; 
grMode: Integer; 
ErrCode: Integer; 
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InitGraph procedure 



begin 

grDriver := Detect; 

InitGraph (grDriver, grMode, " ) ; 

ErrCode := GraphResult; 

if ErrCode = grOk then 

begin 

Line(0, 0, GetMaxX, GetMaxY) ; 

Readln; 

CloseGraph; 
end 
else 

WritelnC Graphics error:', GraphErrorMsg (ErrCode)) 
end. 



{ Do graphics } 



Insert procedure 



D 



Function Inserts a substring into a string. 

Declaration Insert (Source: String; var S: String; Index: Integer) 

Remarks Source is a string-type expression. S is a string-type variable of any length. 
Index is an integer-type expression. Insert inserts Source into S at the 
Indexth position. If the resulting string is longer than 255 characters, it is 
truncated after the 255th character, 

See also Concat, Copy, Delete, Length, Pos 

Example var 

S: String; 
begin 

S := 'Honest Lincoln'; 

Insert ('Abe ', S, 8); { 'Honest Abe Lincoln' } 

end. 



InsLine procedure 



Crt 



Function Inserts an empty line at the cursor position. 

Declaration InsLine 

Remarks All lines below the inserted line are moved down one line, and the bottom 
line scrolls off the screen (using the BIOS scroll routine). 
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InsLine procedure 



All character positions are set to blanks with the currently defined text 
attributes. Thus, if TextBackground is not black, the new line becomes the 
background color. 

This procedure is window-relative and will insert a line 60 columns wide 
at absolute coordinates (1, 10): 

Window (1, 10, 60, 20); 
InsLine; 



See also DelLine, Window 



InstallUserDriver function 



Graph 



Function Installs a vendor-added device driver to the BGI device driver table. 

Declaration InstallUserDriver(Name: String; AutoDetectPtr: Pointer) 
Result type Integer 

Remarks InstallUserDriver allows you to use a vendor-added device driver. The 

Name parameter is the file name of the new device driver. AutoDetectPtr is 
a pointer to an optional autodetect function that may accompany the new 
driver. This autodetect function takes no parameters and returns an 
integer value. 

If the internal driver table is full, InstallUserDriver returns a value of -11 
(grError)', otherwise InstallUserDriver assigns and returns a driver number 
for the new device driver. 

There are two ways to use this vendor-supplied driver. Lefs assume you 
have a new video card called the Spiffy Graphics Array (SGA) and that 
the SGA manufacturer provided you with a BGI device driver (SGA.BGI). 
The easiest way to use this driver is to install it by calling InstallUserDriver 
and then passing the return value (the assigned driver number) directly to 
InitGraph: 

var 

Driver, Mode: Integer; 
begin 

Driver := InstallUserDriver ('SGA', Nil); 

if Driver = grError then ' { Table full? } 

Halt (1) ; 
Mode := 0; { Every driver supports mode of } 

InitGraph (Driver, Mode, "); { Override autodetection } 

{Do graphics . . . } 
end. 
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The nil value for the AutoDetectPtr parameter in the InstallUserDriver call 
indicates there isn't an autodetect function for the SGA. 

The other, more general way to use this driver is to link in an autodetect 
function that will be called by InitGraph as part of its hardware-detection 
logic. Presumably, the manufacturer of the SGA gave you an autodetect 
function that looks something like this: 

{$F+} 

function DetectSGA: Integer; 

var Found: Boolean; 

begin 

DetectSGA := grError; { Assume it's not there } 

Found := ... { Look for the hardware } 

if not Found then 
Exit; { Returns -11 } 

DetectSGA := 3; { Return recommended default video mode } 

end; 
{$F-} 

Detect SGA's job is to look for the SGA hardware at run time. If an SGA is 
not detected, DetectSGA returns a value of -11 (grError); otherwise, the 
return value is the default video mode for the SGA (usually the best mix 
of color and resolution available on this hardware). 

Note that this function takes no parameters, returns a signed, integer-type 
value, and must be a far call. When you install the driver (by calling 
InstallUserDriver), you pass the address of DetectSGA along with the 
device driver's file name: 

var 

Driver, Mode: Integer; 
begin 

Driver := InstallUserDriver ('SGA', @DetectSGA) ; 

if Driver = grError then { Table full? } 

Halt(l); 

Driver := Detect; 

{ Discard SGA driver I; trust autodetection } 

InitGraph (Driver, Mode, "); 

end. 

After you install the device driver file name and the SGA autodetect 
function, you call InitGraph and let it go through its normal autodetection 
process. Before InitGraph calls its built-in autodetection function 
(DetectGraph), it first calls DetectSGA. If DetectSGA doesn't find the SGA 
hardware, it returns a value of -11 {grError) and InitGraph proceeds with 
its normal hardware detection logic (which may include calling any other 
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InstallUserDriver function 



vendor-supplied autodetection functions in the order in which they were 
"installed"). If, however, DetectSGA determines that an SGA is present, it 
returns a nonnegative mode number, and InitGraph locates and loads 
SGA.BGI, puts the hardware into the default graphics mode recom- 
mended by DetectSGA, and finally returns control to your program. 

See also GraphResult, InitGraph, InstallUserFont, RegisterBGIdriver, RegisterBGIfont 

Example uses Graph; 
var 

Driver, Mode, 

TestDriver, 

ErrCode: Integer; 
{$F+} 

function TestDetect: Integer; 
{ Autodetect function: assume hardware is always present; return value = 

recommended default mode } 
begin 

TestDetect := 1; { Default mode = 1 } 

end; 
{$F-} 
begin 

{ Install the driver } 

TestDriver := InstallUserDriver ('TEST', @TestDetect) ; 

if GraphResult <> grOk then 

begin 
WritelnC Error installing TestDriver'); 
Halt(l); 

end; 

Driver := Detect; { Put in graphics mode } 

InitGraph (Driver, Mode, " ) ; 

ErrCode := GraphResult; 

if ErrCode <> grOk then 

begin 

Writeln ('Error during Init: ', ErrCode); 

Halt(l); 
end; 

OutText ('Installable drivers supported...'); 
Readln; 
CloseGraph; 
end. 
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InstallUserFont function 



Graph 



Function Installs a new font not built into the BGI system. 

Declaration function InstallUserFont (FontFileName: String) 
Result type Integer 

Remarks FontFileName is the file name of a stroked font. InstallUserFont returns the 
font ID number that can be passed to SetTextStyle to select this font. If the 
internal font table is full, a value of (DefaultFont) will be returned. 

See also InstallUserDriver, RegisterBGIdriver, RegisterBGIfont, SetTextStyle 

Example uses Graph; 
var 

Driver, Mode: Integer; 
TestFont: Integer; 
begin 

TestFont := InstallUserFont ('TEST' ) ; 
if GraphResult <> grOk then 
begin 

Writeln ('Error installing TestFont (using DefaultFont)'); 

Readln; 
end; 



Q 



{ Install the font } 



Driver := Detect; 

InitGraph (Driver, Mode, " ) ; 

if GraphResult <> grOk then 

Halt(l); 
SetTextStyle (TestFont, HorizDir, 2) ; 
OutTextC Installable fonts supported...'); 
Readln; 
CloseGraph; 
end. 



{ Put in graphics mode } 



{ Use new font } 



Int function 



Function Returns the integer part of the argument. 
Declaration int(X: Real) 
Result type Real 

Remarks X is a real-type expression. The result is the integer part of X, that is, X 
rounded toward zero. 
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See also 
Example 



Frac, Round, Trunc 

var R: Real; 
begin 

R := Int(123.456); 
R := Int (-123. 456); 
end. 



{ 123.0 } 
{ -123.0 } 



Intr procedure 



Dos 



Function Executes a specified software interrupt. 

Declaration Intr(IntNo: Byte; var Regs: Registers) 

Remarks IntNo is the software interrupt number (0..255). Registers is a record 
defined in DOS: 

type 
Registers = record 
case Integer of 

0: (AX, BX, CX, DX, BP, SI, DI, DS, ES, Flags: Word); 
1: (AL, AH, BL, BH, CL, CH, DL, DH: Byte); 
end; 

Before executing the specified software interrupt, Intr loads the 8086 
CPU's AX, BX, CX, DX, BP, SI, DI, DS, and ES registers from the Regs 
record. When the interrupt completes, the contents of the AX, BX, CX, DX, 
BP, SI, DI, DS, ES, and Flags registers are stored back into the Regs record. 

For details on writing interrupt procedures, refer to the section "Interrupt 
handling" in Chapter 18 in the Programmer's Guide. 

Restrictions Software interrupts that depend on specific values in SP or SS on entry, or 
modify SP and SS on exit, cannot be executed using this procedure. 



See also MsDos 



lOResult function 



Function Returns an integer value that is the status of the last I/O operation 
performed. 

Declaration lOResult 

Result type Word 
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Remarks I/O-checking must be off — {$1-} — in order to trap I/O errors using 

lOResult. If an I/O error occurs and I/O-checking is off, all subsequent 
I/O operations are ignored until a call is made to lOResult. A call to 
lOResult clears its internal error flag. 

The codes returned are summarized in Appendix A in the Programmer's 
Guide. A value of reflects a successful I/O operation. 

Example V ar F: file of Byte; 
begin 

{ Get file name command line } 

Assign (F, ParamStr (1) ) ; 

{$1-} 

Reset (F) ; 

{$1+} 

if lOResult = then 

Writeln('File size in bytes: ', FileSize(F)) 
else 

Writeln('File not found'); 
end. 



Q 



Keep procedure 



Dos 



Function Keep (or terminate and stay resident) terminates the program and makes it 
stay in memory. 

Declaration Keep(ExitCode: Word) 

Remarks The entire program stays in memory — including data segment, stack 
segment, and heap — so be sure to specify a maximum size for the heap 
using the $M compiler directive. The ExitCode corresponds to the one 
passed to the Halt standard procedure. 

Restrictions Use with care! Terminate-and-stay-resident (TSR) programs are complex 
and no other support for them is provided. Refer to the MS-DOS technical 
documentation for more information. 

See also DosExitCode 
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KeyPressed function 



Crt 



Function Returns True if a key has been pressed on the keyboard; False otherwise. 
Declaration KeyPressed 

Result type Boolean 

Remarks The character (or characters) is left in the keyboard buffer. KeyPressed does 
not detect shift keys like Shift, Alt, NumLock, and so on. 

See also ReadKey 

Example uses crt; 
begin 
repeat 

Write ('Xx'); { Fill the screen until a key is typed } 

until KeyPressed; 
end. 



Length function 



Function Returns the dynamic length of a string. 

Declaration Length (S: String) 

Result type Integer 

Remarks S is a string-type expression. The result is the length of S. 

See ajso Concat, Copy, Delete, Insert, Pos 

Example V ar 

F: Text; 
S: String; 
begin 

Assign (F, 'GARY. PAS'); 

Reset (F) ; 

Readln(F, S); 

WritelnC"', S, "") 

WritelnC length = ', Length (S)); 



end. 
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Line procedure 



Graph 



Function Draws a line from the (XI, Yl) to (X2, Y2). 

Declaration Line(Xl, Yl, X2, Y2: Integer) 

Remarks Draws a line in the style and thickness defined by SetLineStyle and uses 
the color set by SetColor. Use SetWriteMode to determine whether the line 
is copied or XOR'd to the screen. 

Note that 

MoveTodOO, 100); 
LineTo(200, 200); 

is equivalent to 

Line (100, 100, 200, 200); 
MoveTo(200, 200); 

Use LineTo when the current pointer is at one endpoint of the line. If you 
want the current pointer updated automatically when the line is drawn, 
use LineRel to draw a line a relative distance from the CP. Note that Line 
doesn't update the current pointer. 

Restrictions Must be in graphics mode. Also, for drawing a horizontal line, Bar is faster 
than Line. 

See also GetLineStyle, LineRel, LineTo, MoveTo, Rectangle, SetColor, SetLineStyle, 
SetWriteMode 

Example uses C rt, Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

Randomize; 

repeat 
Line(Random(200), Randora(200), Random(200), Random(200) ) ; 

until KeyPressed; 

Readln; 

CloseGraph; 
end. 



Q 
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LineRel procedure 



Graph 



Function Draws a line to a point that is a relative distance from the current pointer 
(CP). 

Declaration LineRel (Dx, Dy: Integer); 

Remarks LineRel will draw a line from the current pointer to a point that is a 

relative (Dx, Dy) distance from the current pointer. The current line style 
and pattern, as set by SetLineStyle, are used for drawing the line and uses 
the color set by SetColor. Relative move and line commands are useful for 
drawing a shape on the screen whose starting point can be changed to 
draw the same shape in a different location on the screen. Use 
SetWriteMode to determine whether the line is copied or XOR'd to the 
screen. 

The current pointer is set to the last point drawn by LineRel. 

Restrictions Must be in graphics mode. 

See also GetLineStyle, Line, LineTo, MoveRel, MoveTo, SetLineStyle, SetWriteMode 

Example uses Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

MoveTo (1, 2); 

LineRel (100, 100); { Draw to the point (101,102) } 

Readln; 

CloseGraph; 
end. 



LineTo procedure 



Graph 



Function Draws a line from the current pointer to (X, Y). 

Declaration LineTo (X, Y: Integer) 

Remarks Draws a line in the style and thickness defined by SetLineStyle and uses 
the color set by SetColor. Use SetWriteMode to determine whether the line 
is copied or XOR'd to the screen. 
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Note that 

MoveTodOO, 100); 
LineTo (200, 200); 

is equivalent to 

Line (100, 100, 200, 200); 

The first method is slower and uses more code. Use LineTo only when the 
current pointer is at one endpoint of the line. Use LineRel to draw a line a 
relative distance from the CP. Note that the second method doesn't 
change the value of the current pointer. 

LineTo moves the current pointer to (X, Y). 

Restrictions Must be in graphics mode. 

See also GetLineStyle, Line, LineRel, MoveRel, MoveTo, SetLineStyle, SetWriteMode 

Example uses Crt, Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
Randomize; 
repeat 

LineTo (Random (200) , Random (200) ) ; 
until KeyPressed; 
Readln; 
CloseGraph; 
end. 



Q 



Ln function 



Function Returns the natural logarithm of the argument. 

Declaration Ln(X: Real) 

Result type Real 

Remarks X is a real-type expression. The result is the natural logarithm of X. 

See also Exp 
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Lo function 



Function Returns the low-order byte of the argument. 

Declaration Lo (x) 

Result type Byte 

Remarks X is an expression of type Integer or Word. Lo returns the low-order byte 
of X as an unsigned value. 

See also Hi, Swap 

Example var W: Word; 
begin 

W := Lo($1234); { $34 } 
end. 



LowVideo procedure 



Crt 



Function Selects low-intensity characters. 

Declaration LowVideo 

Remarks There is a Byte variable in Crt — TextAttr — that is used to hold the current 
video attribute. LowVideo clears the high-intensity bit of Text Attr's fore- 
ground color, thus mapping colors 8 to 15 onto colors to 7. 

See also HighVideo, NormVideo, TextBackground, TextColor 



Example 



uses Crt; 
begin 

TextAttr := White; 
LowVideo; 
end. 



{ Color is now light gray } 



Mark procedure 



Function Records the state of the heap in a pointer variable. 

Declaration Mark (var P: Pointer) 

Remarks P is a pointer variable of any pointer type. The current value of the heap 
pointer is recorded in P, and can later be used as an argument to Release. 
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Mark procedure 



Mark and Release cannot be used interchangeably with Dispose and 
FreeMem unless certain rules are observed. For a complete discussion of 
this topic, see 'The heap manager" in Chapter 16 of the Programmer's 
Guide, 



See also Dispose, FreeMem, GetMem, New, Release 



MaxAvail function 



Function Returns the size of the largest contiguous free block in the heap, 

corresponding to the size of the largest dynamic variable that can be 
allocated at that time. 

Declaration MaxAvail 

Result type Longint 

Remarks This number is calculated by comparing the sizes of all free blocks below 
the heap pointer to the size of free memory above the heap pointer. To 
find the total amount of free memory on the heap, call MemAvail. Your 
program can specify minimum and maximum heap requirements using 
the $M compiler directive (see Chapter 21 in the Programmer's Guide). 

See also MemAvail 

Example type 

FriendRec = record 

Name: string [30 ]; 

Age: Byte; 
end; 
var 

P: Pointer; 
begin 

if MaxAvail < SizeOf (FriendRec) then 

Writeln('Not enough memory') 
else 
begin 

{ Allocate memory on heap } 

GetMem (P, SizeOf (FriendRec) ) ; 

end; 
end. 



H 
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MemAvail function 



Function Returns the sum of all free blocks in the heap. 

Declaration MemAvail 

Result type Longint 

Remarks This number is calculated by adding the sizes of all free blocks below the 
heap pointer to the size of free memory above the heap pointer. Note that 
unless Dispose and FreeMem were never called, a block of storage the size 
of the returned value is unlikely to be available due to fragmentation of 
the heap. To find the largest free block, call MaxAvail. Your program can 
specify minimum and maximum heap requirements using the $M com- 
piler directive (see Chapter 21 in the Programmer's Guide). 

See also MaxAvail 



Example begin 

Writeln (MemAvail, ' bytes available'); 
WritelnC Largest free block is ', MaxAvail, 
end. 



bytes') ; 



MkDir procedure 



Function Creates a subdirectory. 

Declaration MkDir (S: String) 

Remarks S is a string-type expression. A new subdirectory with the path specified 
by S is created. The last item in the path cannot be an existing file name. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 



See also 


ChDir, GetDir, RmDir 


Example 


begin 




{$1-} 




{ Get directory name from command line } 




MkDir (ParamStr (1) ) ; 




if IOResult <> then 




Writeln ('Cannot create directory') 




else 




Writeln ('New directory created'); 




end. 
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Move procedure 



Function Copies a specified number of contiguous bytes from a source range to a 
destination range. 

Declaration Move(var Source, Dest; Count: Word) 

Remarks Source and Dest are variable references of any type. Count is an expression 
of type Word. Move copies a block of Count bytes from the first byte 
occupied by Source to the first byte occupied by Dest. No checking is 
performed, so be careful with this procedure. 

C^> When Source and Dest are in the same segment, that is, when the segment 
parts of their addresses are equal, Move automatically detects and 
compensates for any overlap. Intrasegment overlaps never occur on 
statically and dynamically allocated variables (unless they are deliberately 
forced), and they are therefore not detected. 

Whenever possible, use the SizeOf function to determine the Count. 

See also FillChar 

Example var 

A: array [1.. 4] of Char; 



H 



B: Longint; 
begin 

Move (A, B, SizeOf (A)] 
end. 



{ SizeOf = safety! } 



MoveRel procedure 



Graph 



Function Moves the current pointer (CP) a relative distance from its current 
location. 

Declaration MoveRel (Dx, Dy: Integer) 

Remarks MoveRel moves the current pointer (CP) to a point that is a relative 
(Dx, Dy) distance from the current pointer. Relative move and line 
commands are useful for drawing a shape on the screen whose starting 
point can be changed to draw the same shape in a different location on the 
screen. 

Restrictions Must be in graphics mode. 

See also GetMaxX, GetMaxY, GetX, GetY, LineRel, LineTo, MoveTo 
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Example uses Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, " ) ; 

if GraphResult <> grOk then 
Halt (1) ; 

MoveTod, 2); 

MoveRel (10, 10); 

PutPixeKGetX, GetY, GetMaxColor) ; 

Readln; 

CloseGraph; 
end. 



{ Move to the point (11, 12) } 



MoveTo procedure 



Graph 



Function Moves the current pointer (CP) to (X, Y). 

Declaration MoveTo (X, Y: Integer) 

Remarks The CP is similar to a text mode cursor except that the CP is not visible. 
The following routines move the CP: 

ClearDevice LineRel OutText 

ClearViewPort LineTo SetGraphMode 

GraphDefaults MoveRel SetViewPort 

InitGraph MoveTo 

If a viewport is active, the CP will be viewport-relative (the X and Y 
values will be added to the viewport's XI and Yl values). The CP is never 
clipped at the current viewport's boundaries. 

See also GetMaxX, GetMaxY, GetX, GetY, MoveRel 

Example uses Graph ; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
MoveTo (0, 0); 
LineTo (GetMaxX, GetMaxY); 
Readln; 



{ Upper left corner of viewport } 



90 



Turbo Pascal Library Reference 



MsDos procedure 



CloseGraph; 
end. 



MsDos procedure 



Dos 



Function Executes a DOS function call. 

Declaration MsDos(var Regs: Registers) 

Remarks The effect of a call to MsDos is the same as a call to Intr with an IntNo of 
$21. Registers is a record declared in the Dos unit: 

type 
Registers = record 
case Integer of 

0: (AX, BX, CX, DX, BP, SI, DI, DS, ES, Flags: Word); 
1: (AL, AH, BL, BH, CL, CH, DL, DH: Byte) ; 
end; 

Restrictions Software interrupts that depend on specific calls in SP or SS on entry or 
modify SP and SS on exit cannot be executed using this procedure. 

See also Mr 



Q 



New procedure 



Function Creates a new dynamic variable and sets a pointer variable to point to it. 

Declaration New(var P: Pointer [ , Init: Constructor ] ) 

Remarks P is a pointer variable of any pointer type. The size of the allocated 

memory block corresponds to the size of the type that P points to. The 
newly created variable can be referenced as P A . If there isn't enough free 
space in the heap to allocate the new variable, a run-time error occurs. (It 
is possible to avoid a run-time error in this case; see "The HeapError 
variable" in Chapter 16 of the Programmer's Guide.) 

New has been extended to allow a constructor call as a second parameter 
for allocating a dynamic object type variable. P is a pointer variable, 
pointing to an object type, and Construct is a call to the constructor of that 
object type. 

An additional extension allows New to be used as a function, which 
allocates and returns a dynamic variable of a specified type. If the call is of 
the form New(P), P can be any pointer type. If the call is of the form 
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New(P, Init), P must point to an object type, and Init must be a call to the 
constructor of that object type. In both cases, the type of the function 
result is P. 

See also Dispose, FreeMem, GetMem, Release 



NormVideo procedure 



Crt 



Function Selects the original text attribute read from the cursor location at startup. 

Declaration NormVideo 

Remarks There is a Byte variable in Crt — TextAttr — that is used to hold the current 
video attribute. NormVideo restores TextAttr to the value it had when the 
program was started. 

See also HighVideo, LowVideo, TextBackground, TextColor 



NoSound procedure 



Crt 



Function Turns off the internal speaker. 
Declaration NoSound 

Remarks The following program fragment emits a 440-hertz tone for half a second: 

Sound (440) ; 
Delay (500); 
NoSound; 

See also Sound 

Odd function 

Function Tests if the argument is an odd number. 

Declaration Odd(X: Longint) 

Result type Boolean 

Remarks X is a Longint-type expression. The result is True if X is an odd number, 
and False if X is an even number. 
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Ofs function 



Function Returns the offset of a specified object. 

Declaration of s (X) 

Result type Word 

Remarks X is any variable, or a procedure or function identifier. The result of type 
Word is the offset part of the address of X. 



See also Addr, Seg 



Ord function 



Function Returns the ordinal number of an ordinal-type value. 
Declaration ord(x) 
Result type Longint 

Remarks X is an ordinal-type expression. The result is of type Longint and its value 
is the ordinality of X. 



See also Chr 



M 



OutText procedure 



Graph 



Function Sends a string to the output device at the current pointer. 

Declaration OutText (TextString: String) 

Remarks TextString is output at the current pointer using the current justification 
settings. TextString is always truncated at the viewport border if it is too 
long. If one of the stroked fonts is active, TextString is truncated at the 
screen boundary if it is too long. If the default (bit-mapped) font is active 
and the string is too long to fit on the screen, no text is displayed. 

OutText uses the font set by SetTextStyle. In order to maintain code com- 
patibility when using several fonts, use the TextWidth and TextHeight calls 
to determine the dimensions of the string. 

OutText uses the output options set by SetTextJustify (justify, center, rotate 
90 degrees, and so on). 
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The current pointer (CP) is only updated by OutText if the direction is 
horizontal, and the horizontal justification is left. Text output direction is 
set by SetTextStyle (horizontal or vertical); text justification is set by 
SetTextJustify (CP at the left of the string, centered around CP, or CP at the 
right of the string — written above CP, below CP, or centered around CP). 
In the following example, block #1 outputs ABCDEF and moves CP (text 
is both horizontally output and left-justified); block #2 outputs ABC with 
DEF written right on top of it because text is right-justified; similarly, 
block #3 outputs ABC with DEF written right on top of it because text is 
written vertically. 

program CPupdate; 
uses Graph; 
var 

Driver, Mode: Integer; 
begin 

Driver := Detect; 

InitGraph (Driver, Mode, "); 

if GraphResult < then 
Halt(l); 

{ #1 } 

MoveTo(0, 0); 

SetTextStyle (DefaultFont, HorizDir, 1) ; 

SetTextJustify (Left Text, TopText) ; 

OutText ('ABC') ; 

OutText ('DEF'); 

{ #2 } 

MoveTo(100, 50); 

SetTextStyle (DefaultFont, HorizDir, 1) ; 

SetTextJustify (RightText, TopText) ; 

Out Text ('ABC') ; 

OutText ('DEF') ; 

{ #3 } 

MoveTodOO, 100); 

SetTextStyle (DefaultFont, VertDir, 1) ; 

SetTextJustify (LeftText, TopText) ; 

OutText ('ABC') ; 

OutText ('DEF') ; 

Readln; 

CloseGraph; 
end. 



{ CharSize = 1 } 

{ CP is updated } 
{ CP is updated } 



( CharSize = 1 } 

{ CP is updated } 
{ CP is updated } 



{ CharSize = 1 } 

{ CP is NOT updated } 
{ CP is NOT updated } 



The CP is never updated by OutTextXY. 

The default font (8x8) is not clipped at the screen edge. Instead, if any part 
of the string would go off the screen, no text is output. For example, the 
following statements would have no effect: 
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SetViewPort(0, 0, GetMaxX, GetMaxY, ClipOn) ; 
SetText Justify (LeftText, TopText) ; 
0utTextXY(-5, 0); 
OutTextXY (GetMaxX - 1, 0, 'ABC'); 



{ -5,0 not onscreen } 

{ Part of 'A', } 

{ All of 'BC off screen } 



The stroked fonts are clipped at the screen edge, however. 

Restrictions Must be in graphics mode. 

See also GetTextSettings, OutTextXY, SetTextJustify, SetTextStyle, SetUserCharSize, 
TextHeight, TextWidth 

Example uses Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

OutText ('Easy to use'); 

Readln; 

CloseGraph; 
end. 



OutTextXY procedure 



Graph 



Function Sends a string to the output device. 

Declaration OutTextXY(X, Y: Integer; TextString: String) 

Remarks TextString is output at (X, Y). TextString is always truncated at the 
viewport border if it is too long. If one of the stroked fonts is active, 
TextString is truncated at the screen boundary if it is too long. If the 
default (bit-mapped) font is active and the string is too long to fit on the 
screen, no text is displayed. 

Use OutText to output text at the current pointer; use OutTextXY to output 
text elsewhere on the screen. 

OutTextXY uses the font set by SetTextStyle. In order to maintain code 
compatibility when using several fonts, use the TextWidth and TextHeight 
calls to determine the dimensions of the string. 

OutTextXY uses the output options set by SetTextJustify (justify, center, 
rotate 90 degrees, and so forth). 



H 
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Restrictions Must be in graphics mode. 

See also GetTextSettings, OutText, SetTextJustify, SetTextStyle, SetUserCharSize, 
TextHeight, TextWidth 

Example uses Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

MoveTo(0, 0); 

OutText (' Inefficient' ) ; 

Readln; 

OutTextXY (GetX, GetY, 'Also inefficient') ; 

Readln; 

ClearDevice; 

OutTextXY (0, 0, 'Perfect!'); { Replaces above } 

Readln; 

CloseGraph; 
end. 



OvrClearBuf procedure 



Overlay 



Function Clears the overlay buffer. 

Declaration OvrClearBuf 

Remarks Upon a call to OvrClearBuf, all currently loaded overlays are disposed 

from the overlay buffer. This forces subsequent calls to overlaid routines 
to reload the overlays from the overlay file (or from EMS). If OvrClearBuf 
is called from an overlay, that overlay will immediately be reloaded upon 
return from OvrClearBuf. The overlay manager never requires you to call 
OvrClearBuf; in fact, doing so will decrease performance of your appli- 
cation, since it forces overlays to be reloaded. OvrClearBuf is solely 
intended for special use, such as temporarily reclaiming the memory 
occupied by the overlay buffer. 

See also OvrGetBuf, OvrSetBuf 
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OvrGetBuf function 



Overlay 



Function Returns the current size of the overlay buffer. 

Declaration OvrGetBuf 

Result type Longint 

Remarks The size of the overlay buffer is set through a call to OvrSetBuf. Initially, 
the overlay buffer is as small as possible, corresponding to the size of the 
largest overlay. A buffer of this size is automatically allocated when an 
overlaid program is executed. (Note: The initial buffer size may be larger 
than 64K, since it includes both code and fix-up information for the largest 
overlay.) 

See also Ovrlnit, OvrlnitEMS, OvrSetBuf 

Example { $ M 16384,65536,655360} 
uses Overlay; 
const 

ExtraSize = 49152; {48K} 
begin 

Ovrlnit (' EDITOR. OVR'); 

WritelnC Initial size of overlay buffer is ', OvrGetBuf,' bytes.'); 

OvrSetBuf (OvrGetBuf +ExtraSize) ; 

WritelnC Overlay buffer now increased to ', OvrGetBuf,' bytes.'); 
end. 



^ 



Ovrlnit procedure 



Overlay 



Function Initializes the overlay manager and opens the overlay file. 

Declaration OvrInit(FileName: String) 

Remarks If the file-name parameter does not specify a drive or a subdirectory, the 
overlay manager searches for the file in the current directory, in the 
directory that contains the .EXE file (if running under DOS 3.x), and in the 
directories specified in the PATH environment variable. 

Errors are reported in the OvrResult variable. ovrOk indicates success. 
ovrError means that the overlay file is of an incorrect format, or that the 
program has no overlays. ovrNotFound means that the overlay file could 
not be located. 
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In case of error, the overlay manager remains uninstalled, and an attempt 
to call an overlaid routine will produce run-time error 208 ("Overlay 
manager not installed"). 

Ovrlnit must be called before any of the other overlay manager 
procedures. 

See also OvrGetBuf, OvrlnitEMS, OvrSetBuf 

Example use s Overlay; 
begin 

Ovrlnit (' EDITOR. OVR'); 
if OvrResultOovrOk then 
begin 
case OvrResult of 
ovrError: WritelnC Program has no overlays.'); 
ovrNotFound: WritelnC Overlay file not found.'); 
end; 

Halt(l); 
end; 
end. 



OvrlnitEMS procedure 



Overlay 



Function Loads the overlay file into EMS if possible. 

Declaration OvrlnitEMS 

Remarks If an EMS driver can be detected and if enough EMS memory is available, 
OvrlnitEMS loads all overlays into EMS and closes the overlay file. 
Subsequent overlay loads are reduced to fast in-memory transfers. 
OvrlnitEMS installs an exit procedure, which automatically deallocates 
EMS memory upon termination of the program. 

Errors are reported in the OvrResult variable. ovrOk indicates success. 
ovrError means that Ovrlnit failed or was not called. ovrlOError means that 
an I/O error occurred while reading the overlay file. ovrNoEMSDriver 
means that an EMS driver could not be detected. ovrNoEMSMemory 
means that there is not enough free EMS memory available to load the 
overlay file. 

In case of error, the overlay manager will continue to function, but 
overlays will be read from disk. 

The EMS driver must conform to the Lotus/Intel/Microsoft Expanded 
Memory Specification (EMS). If you are using an EMS-based RAM disk, 
make sure that the command in the CONFIG.SYS file that loads the 
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RAM-disk driver leaves some unallocated EMS memory for your overlaid 
applications. 

See also OvrGetBuf, Ovrlnit, OvrSetBuf 

Example uses Overlay; 
begin 

Ovrlnit (' EDITOR. OVR'); 
if OvrResultOovrOk then 
begin 

Writeln ('Overlay manager initialization failed.'); 

Halt(l); 
end; 

OvrlnitEMS; 
case OvrResult of 

ovrlOError: Writeln ('Overlay file I/O error.'); 

ovrNoEMSDriver: Writeln ('EMS driver not installed.'); 

ovrNoEMSMemory : Writeln ('Not enough EMS memory.'); 

else Writeln ('Using EMS for faster overlay swapping.'); 
end; 
end; 



OvrSetBuf procedure 



Overlay 



Function Sets the size of the overlay buffer. 

Declaration OvrSetBuf (BufSize: Longint) 

Remarks BufSize must be larger than or equal to the initial size of the overlay buffer, 
and less than or equal to MemAvail + OvrGetBuf. The initial size of the 
overlay buffer is the size returned by OvrGetBuf 'before any calls to 
OvrSetBuf. 

If the specified size is larger than the current size, additional space is 
allocated from the beginning of the heap, thus decreasing the size of the 
heap. Likewise, if the specified size is less than the current size, excess 
space is returned to the heap. 

OvrSetBuf requires that the heap be empty; an error is returned if dynamic 
variables have already been allocated using New or GetMem. For this 
reason, make sure to call OvrSetBuf before the Graph unit's InitGraph 
procedure; InitGraph allocates memory on the heap and — once it has done 
so — all calls to OvrSetBuf will be ignored. 
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If you are using OvrSetBuf to increase the size of the overlay buffer, you 
should also include a $M compiler directive in your program to increase 
the minimum size of the heap accordingly. 

Errors are reported in the OvrResult variable. ovrOk indicates success. 
ovrError means that Ovrlnit failed or was not called, that BufSize is too 
small, or that the heap is not empty. ovrNoMemory means that there is not 
enough heap memory to increase the size of the overlay buffer. 

See also OvrGetBuf, Ovrlnit, OvrlnitEMS 

Example { $ M 16384,65536,655360} 
uses Overlay; 
const 

ExtraSize = 49152; {48K} 
begin 

Ovrlnit (' EDITOR. OVR'); 

OvrSetBuf (OvrGetBuf + ExtraSize); 
end. 



PackTime procedure 



Dos 



Function Converts a DateTime record into a 4-byte, packed date-and-time Longint 
used by SetFTime. 

Declaration PackTime (var DT: DateTime; var Time: Longint) 

Remarks DateTime is a record declared in the Dos unit: 

DateTime = record 

Year, Month, Day, Hour, Min, Sec: Word; 
end; 

The fields of the DateTime record are not range-checked. 

See also GetFTime, GetTime, SetFTime, SetTime, UnpackTime 

ParamCount function 

Function Returns the number of parameters passed to the program on the 
command line. 

Declaration ParamCount 

Result type Word 
Remarks Blanks and tabs serve as separators. 
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See also ParamStr 

Example begin 

if ParamCount < 1 then 

Writeln('No parameters on command line') 
else 
Writeln (ParamCount, ' parameter (s) ' ) ; 
end. 



ParamStr function 



Function Returns a specified command-line parameter. 

Declaration ParamStr (Index) 

Result type String 

Remarks Index is an expression of type Word. ParamStr returns the Indexth. 

parameter from the command line, or an empty string if Index is zero or 
greater than ParamCount With DOS 3.0 or later, ParamStr(O) returns the 
path and file name of the executing program (for example, C:\TP\ 
MYPROG.EXE). 



See also 


ParamCount 


Example 


var I: Word; 
begin 

for I := 1 to ParamCount do 
Writeln (ParamStr (I) ) ; 
end. 


Pi function 




Function 


Returns the value of Pi (3.1415926535897932385). 


Declaration 


Pi 


Result type 


Real 



ffi 



Remarks Precision varies, depending on whether the compiler is in 8087 (80287, 
80387) or software-only mode. 
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PieSlice procedure 



Graph 



Function Draws and fills a pie slice, using (X, Y) as the center point and drawing 
from start angle to end angle. 

Declaration PieSlice (X, Y: Integer; StAngle, EndAngle, Radius: Word) 

Remarks The pie slice is outlined using the current color, and filled using the 
pattern and color defined by SetFillSiyle or SetFillPattern. 

Each graphics driver contains an aspect ratio that is used by Circle, Arc, 
and PieSlice. A start angle of and an end angle of 360 will draw and fill a 
complete circle. The angles for Arc, Ellipse, and PieSlice are counterclock- 
wise with degrees at 3 o'clock, 90 degrees at 12 o'clock, and so on. 

If an error occurs while filling the pie slice, GraphResult returns a value of 
-6 (grNoScanMem). 

Restrictions Must be in graphics mode. 

See also Arc, Circle, Ellipse, FillEllipse, GetArcCoords, GetAspectRatio, Sector, 
SetFillStyle, SetFillPattern, SetGraphBufSize 

Example uses Graph; 
const 

Radius =30; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

PieSlice (100, 100, 0, 270, Radius); 

Readln; 

CloseGraph; 
end. 



Pos function 



Function Searches for a substring in a string. 

Declaration Pos(Substr, S: String) 
Result type Byte 
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Remarks Substr and S are string-type expressions. Pos searches for Substr within S, 
and returns an integer value that is the index of the first character of 
Substr within S. If Substr is not found, Pos returns zero. 

See also Concat, Copy, Delete, Insert, Length 

Example var S: String; 
begin 

S := ' 123.5'; 
{ Convert spaces to zeroes } 
while PosC ', S) > do 
S[Pos(' ', S)] := 'OS- 
end. 



Pred function 



Function Returns the predecessor of the argument. 

Declaration Pred(x) 

Result type Same type as parameter. 

Remarks X is an ordinal-type expression. The result, of the same type as X, is the 



predecessor of X. 
See also Dec, Inc, Succ 



Ptr function 



Function Converts a segment base and an offset address to a pointer-type value. 

Declaration Ptr(Seg, Ofs: Word) 

Result type Pointer 

Remarks Seg and Ofs are expressions of type Word. The result is a pointer that 
points to the address given by Seg and Ofs. Like nil, the result of Ptr is 
assignment-compatible with all pointer types. 

The function result may be dereferenced and typecast: 



n 



if Byte (Ptr ($40, $49) A ) = 7 then 
Writeln ('Video mode = mono'); 



See also Addr, Ofs, Seg 
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Example V ar P: A Byte; 
begin 

P := Ptr($40, $49); 

WritelnC Current video mode is ', P A ); 
end. 



Putlmage procedure 



Graph 



Function 

Declaration 

Remarks 



Puts a bit image onto the screen. 

Putlmage (X, Y: Integer; var BitMap; BitBlt: 



Word) 



(X, Y) is the upper left corner of a rectangular region on the screen. BitMap 
is an untyped parameter that contains the height and width of the region, 
and the bit image that will be put onto the screen. Bit Bit specifies which 
binary operator will be used to put the bit image onto the screen. 

The following constants are defined: 



const 

CopyPut 

XORPut 

OrPut 

AndPut 

NotPut 



= 
= 1 
= 2 
= 3 
= 4 



{ MOV } 

{ XOR } 

{ OR } 

{ AND } 

{ NOT } 



Each constant corresponds to a binary operation. For example, 
PutImage(X, Y, BitMap, NormalPut) puts the image stored in BitMap at (X, 
Y) using the assembly language MOV instruction for each byte in the 
image. 

Similarly, PutImage(X, Y, BitMap, XORPut) puts the image stored in 
BitMap at (X, Y) using the assembly language XOR instruction for each 
byte in the image. This is an often-used animation technique for 
"dragging" an image around the screen. 

PutImage(X, Y, BitMap, NotPut) inverts the bits in BitMap and then puts 
the image stored in BitMap at (X, Y) using the assembly language MOV for 
each byte in the image. Thus, the image appears in inverse video of the 
original BitMap. 

Note that Putlmage is never clipped to the viewport boundary. 
Moreover — with one exception — it is not actually clipped at the screen 
edge either. Instead, if any part of the image would go off the screen, no 
image is output. In the following example, the first image would be 
output, but the middle three Putlmage statements would have no effect: 
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program NoClip; 
uses Graph; 
vax 

Driver, Mode: Integer; 
P: Pointer; 
begin 

Driver := Detect; 

InitGraph (Driver, Mode, " ) ; 

if GraphResult < then 

Halt(l); 
SetViewPort(0, 0, GetMaxX, GetMaxY, ClipOn) ; 
GetMem(p, ImageSize(0, 0, 99, 49)); 
PieSlice(50, 25, 0, 360, 45); 
GetIraage(0, 0, 99, 49, P A ); 
ClearDevice; 
Putlmage (GetMaxX - 99, 0, 

P A , NormalPut) ; 
Putlmage (GetMaxX - 98, 0, 

P A , NormalPut) ; 
Putlmage (-1, 0, 

P A , NormalPut); 
Putlmage (0, -1, 

P A , NormalPut); 
Putlmage (0, GetMaxY - 30, 

P A , NormalPut); 
Readln; 
CloseGraph; 
end. 

In the last Putlmage statement, the height is clipped at the lower screen 
edge, and a partial image is displayed. This is the only time any clipping 
is performed on Putlmage output. 

Restrictions Must be in graphics mode. 

See also Getlmage, ImageSize 

Example us6 s Graph; 
var 

Gd, Gm: Integer; 
P: Pointer; 
Size: Word; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt UK- 
Bar (0, 0, GetMaxX, GetMaxY); 
Size := ImageSize (10, 20, 30, 40); 



{ Width = 100, height = 50 } 

{ Will barely fit } 

{ X + Height > GetMaxX } 

{ -1,0 not onscreen } 

{ 0,-1 not onscreen } 

{ Will output 31 "lines" } 



m 
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GetMem(P, Size); 
Getlmage(10, 20, 30, 40, P A ) ; 
Readln; 
ClearDevice; 

Putlmage (100, 100, P A , NormalPut) ; 
Readln; 
CloseGraph; 
end. 



{ Allocate memory on heap } 



PutPixel procedure 



Graph 



Function Plots a pixel at X, Y 

Declaration PutPixel(X, Y: Integer; Pixel: Word) 

Remarks Plots a point in the color defined by Pixel at (X, Y). 

Restrictions Must be in graphics mode. 

See also Getlmage, GetPixel, Putlmage 

Example uses Cr t, Graph; 
var 

Gd, Gm: Integer; 
Color: Word; 
begin 
Gd := Detect; 
InitGraph(Gd, Gm, "); 
if GraphResult <> grOk then 

Halt(l); 
Color := GetMaxColor; 
Randomize; 
repeat 

PutPixel (Random (100), Random(lOO), Color); 

Delay ( 10); 
until KeyPressed; 
Readln; 
CloseGraph; 
end. 



{ Plot "stars" } 
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Random function 



Function Returns a random number. 



Declaration Random 

Result type 
Remarks 



Range: Word) ] 
Real or Word, depending on the parameter 



If Range is not specified, the result is a Real random number within the 
range <= X < 1. If Range is specified, it must be an expression of type 
Integer, and the result is a Word random number within the range <= X 
< Range. If Range equals 0, a value of will be returned. 

The Random number generator should be initialized by making a call to 
Randomize, or by assigning a value to RandSeed. 

See also Randomize 

Example uses crt; 
begin 

Randomize; 
repeat 

{ Write text in random colors } 

TextAttr := Random(256); 

Write('!'); 
until KeyPressed; 
end. 



Randomize procedure 



Function Initializes the built-in random generator with a random value. 

Declaration Randomize 

Remarks The random value is obtained from the system clock. 

C^> The random-number generator's seed is stored in a predeclared Longint 
variable called RandSeed. By assigning a specific value to RandSeed, a 
specific sequence of random numbers can be generated over and over. 
This is particularly useful in applications that use data encryption. 

See also Random 
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Read procedure (text files) 



Function Reads one or more values from a text file into one or more variables. 

Declaration Read( [ var F: Text; ] VI [, V2, ...,Vff] ) 

Remarks F, if specified, is a text-file variable. If F is omitted, the standard file 

variable Input is assumed. Each V is a variable of type Char, Integer, Real, 
or String. 

With a type Char variable, Read reads one character from the file and 
assigns that character to the variable. If EofiF) was True before Read was 
executed, the value Chr{26) (a Ctrl-Z character) is assigned to the variable. If 
Eoln(F) was True, the value ChrQS) (a carriage-return character) is 
assigned to the variable. The next Read will start with the next character in 
the file. 

With a type integer variable, Read expects a sequence of characters that 
form a signed number, according to the syntax shown in the section 
"Numbers" in Chapter 1 of the Programmer's Guide. Any blanks, tabs, or 
end-of-line markers preceding the numeric string are skipped. Reading 
ceases at the first blank, tab, or end-of-line marker following the numeric 
string or if EofiF) becomes True. If the numeric string does not conform to 
the expected format, an I/O error occurs; otherwise/the value is assigned 
to the variable. If EofiF) was True before Read was executed or if EofiF) 
becomes True while skipping initial blanks, tabs, and end-of-line markers, 
the value is assigned to the variable. The next Read will start with the 
blank, tab, or end-of-line marker that terminated the numeric string. 

With a type real variable, Read expects a sequence of characters that form 
a signed whole number, according to the syntax shown in the section 
"Numbers" in Chapter 1 of the Programmer's Guide (except that 
hexadecimal notation is not allowed). Any blanks, tabs, or end-of-line 
markers preceding the numeric string are skipped. Reading ceases at the 
first blank, tab, or end-of-line marker following the numeric string or if 
EofiF) becomes True. If the numeric string does not conform to the 
expected format, an I/O error occurs; otherwise, the value is assigned to 
the variable. If EofiF) was True before Read was executed, or if EofiF) 
becomes True while skipping initial blanks, tabs, and end-of-line markers, 
the value is assigned to the variable. The next Read will start with the 
blank, tab, or end-of-line marker that terminated the numeric string. 

With a type string variable, Read reads all characters up to, but not 
including, the next end-of-line marker or until EofiF) becomes True. The 
resulting character string is assigned to the variable. If the resulting string 
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is longer than the maximum length of the string variable, it is truncated. 
The next Read will start with the end-of-line marker that terminated the 
string. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Restrictions Read with a type string variable does not skip to the next line after 

reading. For this reason, you cannot use successive Read calls to read a 
sequence of strings, since you will never get past the first line; after the 
first Read, each subsequent Read will see the end-of-line marker and return 
a zero-length string. Instead, use multiple Readln calls to read successive 
string values. 

See also Readln, ReadKey, Write, Writeln 



Read procedure (typed files) 



Function Reads a file component into a variable. 

Declaration Read(F, vi [, v2,...,vn] ) 

Remarks F is a file variable of any type except text, and each V is a variable of the 
same type as the component type of F. For each variable read, the current 
file position is advanced to the next component. If s an error to attempt to 
read from a file when the current file position is at the end of the file, that 
is, when Eof(F) is True. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 



Restrictions File must be open. 
See also Write 

ReadKey function 



Crt 



a 



Function Reads a character from the keyboard. 

Declaration ReadKey 

Result type Char 

Remarks The character read is not echoed to the screen. If KeyPressed was True 
before the call to ReadKey, the character is returned immediately. 
Otherwise, ReadKey waits for a key to be typed. 
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The special keys on the PC keyboard generate extended scan codes. (The 
extended scan codes are summarized in Appendix B of the Programmer's 
Guide.) Special keys are the function keys, the cursor control keys, Alt keys, 
and so on. When a special key is pressed, ReadKey first returns a null 
character (#0), and then returns the extended scan code. Null characters 
cannot be generated in any other way, so you are guaranteed the next 
character will be an extended scan code. 

The following program fragment reads a character or an extended scan 
code into a variable called Ch and sets a Boolean variable called FuncKey 
to True if the character is a special key: 

Ch := ReadKey; 

if Ch <> #0 then FuncKey := False else 

begin 

FuncKey := True; 

Ch := ReadKey; 
end; 

The CheckBreak variable controls whether Ctrl-Break should abort the 
program or be returned like any other key. When CheckBreak is False, 
ReadKey returns a Ctrl-C (#3) for Ctrl-Break. 

See also KeyPressed 



Readln procedure 



Function Executes the Read procedure then skips to the next line of the file. 

Declaration Readln ( [ var F: Text; ] VI [, V2,...,W ] ) 

Remarks Readln is an extension to Read, as it is defined on text files. After executing 
the Read, Readln skips to the beginning of the next line of the file. 

Readln(F) with no parameters causes the current file position to advance to 
the beginning of the next line (if there is one; otherwise, it goes to the end 
of the file). Readln with no parameter list altogether corresponds to 
ReadlnQnput). 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Restrictions Works only on text files, including standard input. File must be open for 
input. 

See also Read 
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Rectangle procedure 



Graph 



Function Draws a rectangle using the current line style and color. 

Declaration Rectangle (XI, Yl, X2, Y2: Integer) 

Remarks (XI, Yl) define the upper left corner of the rectangle, and (X2, Y2) define 
the lower right corner (0 <= XI < X2 <= GetMaxX, and <= Yl < Y2 <= 

GetMaxY). 

The rectangle will be drawn in the current line style and color, as set by 
SetLineStyle and SetColor. Use SetWriteMode to determine whether the 
rectangle is copied or XOR'd to the screen. 

Restrictions Must be in graphics mode. 

See also Bar, Bar3D, GetViewSettings, InitGraph, SetColor, SetLineStyle, SetViezvPort, 
SetWriteMode 

Example uses Crt, Graph; 
var 

GraphDriver, GraphMode: Integer; 
XI, Yl, X2, Y2: Integer; 
begin 

GraphDriver := Detect; 

InitGraph (GraphDriver, GraphMode, "); 

if GraphResulto grOk then 

Halt(l); 
Randomize; 
repeat 

XI := Random (GetMaxX); 

Yl := Random (GetMaxY); 

X2 := Random (GetMaxX - XI) + XI; 

Y2 := Random (GetMaxY - Yl) + Yl; 

Rectangle (XI, Yl, X2, Y2); 
until KeyPressed; 
CloseGraph; 
end. 
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RegisterBGIdriver function 



Graph 



Function Registers a user-loaded or linked-in BGI driver with the graphics system. 

Declaration RegisterBGIdriver (Driver: Pointer): Integer; 

Remarks If an error occurs, the return value is less than 0; otherwise, the internal 
driver number is returned. 

This routine enables a user to load a driver file and "register" the driver 
by passing its memory location to RegisterBGIdriver. When that driver is 
used by InitGraph, the registered driver will be used (instead of being 
loaded from disk by the Graph unit). A user-registered driver can be 
loaded from disk onto the heap, or converted to an .OBJ file (using 
BINOBJ.EXE) and linked into the .EXE. 

grlnvalidDriver is a possible error return, where the error code equals -4 
and the driver header is not recognized. 

The following program loads the CGA driver onto the heap, registers it 
with the graphics system, and calls InitGraph: 

program LoadDriv; 
uses Graph; 
var 

Driver, Mode: Integer; 
DriverF: file; 
DriverP: Pointer; 
begin 

{ Open driver file, read into memory, register it } 

Assign (DriverF, ' CGA. BGI'); 

Reset (DriverF, 1); 

GetMem (DriverP, FileSize (DriverF) ) ; 

BlockRead (DriverF, DriverP A , FileSize (DriverF) ) ; 

if RegisterBGIdriver (DriverP) < then 

begin 

WritelnC Error registering driver: ', 
GraphErrorMsg(GraphResult) ) ; 

Halt(l); 
end; 

{ Init graphics } 
Driver := CGA; 
Mode := CGAHi; 
InitGraph (Driver, Mode, "); 
if GraphResult < then 

Halt(l); 
OutText ('Driver loaded by user program'); 
Readln; 



112 



Turbo Pascal Library Reference 



RegisterBGIdriver function 



CloseGraph; 
end. 

The program begins by loading the CGA driver file from disk and 
registering it with the Graph unit. Then a call is made to InitGraph to 
initialize the graphics system. You may wish to incorporate one or more 
driver files directly into your .EXE file. In this way, the graphics drivers 
that your program needs will be built-in and only the .EXE will be needed 
in order to run. The process for incorporating a driver file into your .EXE 
is straightforward: 

1. Run BINOBJ on the driver file(s). 

2. Link the resulting .OBJ file(s) into your program. 

3. Register the linked-in driver file(s) before calling InitGraph. 

For a detailed explanation and example of the preceding, refer to the 
comments at the top of the BGILINK.PAS example program on the 
distribution disks. For information on the BINOBJ utility, refer to the file 
UTIL.DOC (in ONLINE.ZIP) on your distribution disks. 

It is also possible to register font files; refer to the description of 
RegisterBGIfont. 

Restrictions Note that the driver must be registered before the call to InitGraph. If a call 
is made to RegisterBGIdriver once graphics have been activated, a value of 
-11 igrError) will be returned. If you want to register a user-provided 
driver, you must first call InstallUserDriver, then proceed as described in 
the previous example. 

See also InitGraph, InstallUserDriver, RegisterBGIfont 

RegisterBGIfont function Graph 

Function Registers a user-loaded or linked-in BGI font with the graphics system. 

Declaration RegisterBGIfont (Font: Pointer): Integer; 

Remarks The return value is less than if an error occurs; otherwise, the internal 

font number is returned. This routine enables a user to load a font file and 
"register" the font by passing its memory location to RegisterBGIfont. 
When that font is selected with a call to SetTextStyle, the registered font 
will be used (instead of being loaded from disk by the Graph unit). A 
user-registered font can be loaded from disk onto the heap, or converted 
to an .OBJ file (using BINOBJ.EXE) and linked into the .EXE. 
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RegisterBGIfont function 



Here are some possible error returns: 



Error Error 

code identifier Comments 



-11 grError There is no room in the font table to 

register another font. (The font table holds 
up to 10 fonts, and onl^ are provided, so 
this error should not occur.) 

-13 grlnvalidFont The font header is not recognized. 

-14 grlnvalidFontNum The font number in the font header is not 

recognized. 

The following program loads the triplex font onto the heap, registers it 
with the graphics system, and then alternates between using triplex and 
another stroked font that Graph loads from disk (SansSerifFont): 

program LoadFont; 
uses Graph; 
var 

Driver, Mode: Integer; 
FontF: file; 
FontP: Pointer; 
begin 

{ Open font file, read into memory, register it } 

Assign (FontF, ' TRIP .CHR' ) ; 

Reset (FontF, 1); 

GetMem (FontP, FileSize (FontF) ) ; 

BlockRead (FontF, FontP", FileSize (FontF) ) ; 

if RegisterBGIfont (FontP) < then 

begin 

WritelnC Error registering font: ', GraphErrorMsg(GraphResult) ) ; 

Halt(l); 
end; 

{ Init graphics } 
Driver := Detect; 
InitGraph (Driver, Mode, ' . . V ) ; 
if GraphResult < then 

Halt(l); 
Readln; 

{ Select registered font } 
SetTextStyle (TriplexFont, HorizDir, 4); 
Out Text ('Triplex loaded by user program'); 
MoveTo(0, TextHeight('a')); 
Readln; 

{ Select font that must be loaded from disk } 
SetTextStyle (SansSerifFont, HorizDir, 4); 
OutText('Your disk should be spinning...'); 
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MoveTo(0, GetY + TextHeight ('a') ) ; 
Readln; 

{ Re-select registered font (already in memory) } 
SetTextStyle(TriplexFont, HorizDir, 4); 
Out Text ('Back to Triplex'); 
Readln; 
CloseGraph; 
end. 

The program begins by loading the triplex font file from disk and 
registering it with the Graph unit. Then a call to InitGraph is made to 
initialize the graphics system. Watch the disk drive indicator and press 
Enter. Because the triplex font is already loaded into memory and regis- 
tered, Graph does not have to load it from disk (and therefore your disk 
drive should not spin). Next, the program will activate the sans serif font 
by loading it from disk (it is unregistered). Press Enter again and watch the 
drive spin. Finally, the triplex font is selected again. Since it is in memory 
and already registered, the drive will not spin when you press Enter. 

There are several reasons to load and register font files. First, Graph only 
keeps one stroked font in memory at a time. If you have a program that 
needs to quickly alternate between stroked fonts, you may want to load 
and register the fonts yourself at the beginning of your program. Then 
Graph will not load and unload the fonts each time a call to SetTextStyle is 
made. 

Second, you may wish to incorporate the font files directly into your .EXE 
file. This way, the font files that your program needs will be built-in, and 
only the .EXE and driver files will be needed in order to run. The process 
for incorporating a font file into your .EXE is straightforward: 

1. Run BINOBJ on the font file(s). 

2. Link the resulting .OBJ file(s) into your program. 

3. Register the linked-in font file(s) before calling InitGraph. 

For a detailed explanation and example of the preceding, refer to the 
comments at the top of the BGILINK.PAS example program on the distri- 
bution disks. Documentation on the BINOBJ utility is available in the file 
UTIL.DOC (in ONLINE.ZIP) on your distribution disks. 

Note that the default (8x8 bit-mapped) font is built into GRAPH.TPU, and 
thus is always in memory. Once a stroked font has been loaded, your 
program can alternate between the default font and the stroked font 
without having to reload either one of them. 
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It is also possible to register driver files; refer to the description of 
RegisterBGIdriver. 

See also InitGraph, InstallUserDriver, InstallUserFont, RegisterBGIfont, SetTextStyle 

Release procedure 

Function Returns the heap to a given state. 

Declaration Release (var P: Pointer) 

Remarks P is a pointer variable of any pointer type that was previously assigned by 
the Mark procedure. Release disposes all dynamic variables that were 
allocated by New or GetMem since P was assigned by Mark. 

Restrictions Mark and Release cannot be used interchangeably with Dispose and 

FreeMem unless certain rules are observed. For a complete discussion of 
this topic, refer to the section "The heap manager" in Chapter 16 of the 
Programmer's Guide. 

See also Dispose, FreeMem, GetMem, Mark, New 



Rename procedure 



Function Renames an external file. 

Declaration Rename (var F; Newname: String) 

Remarks F is a file variable of any file type. Newname is a string-type expression. 
The external file associated with F is renamed to Newname. Further 
operations on F will operate on the external file with the new name. 

With {$1-}, IOResult returns if the operation was successful; otherwise, it 
returns a nonzero error code. 

Restrictions Rename must never be used on an open file. 

See also Erase 
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Reset procedure 



Function 

Declaration 

Remarks 



See also 
Example 



Opens an existing file. 

Reset (var F [: file; RecSize: 



Word) 



F is a file variable of any file type, which must have been associated with 
an external file using Assign. RecSize is an optional expression of type 
Word, which can only be specified if F is an untyped file. 

Reset opens the existing external file with the name assigned to F. It's an 
error if no existing external file of the given name exists. If F was already 
open, it is first closed and then re-opened. The current file position is set 
to the beginning of the file. 

If F was assigned an empty name, such as Assign(F, "), then after the call 
to Reset, F will refer to the standard input file (standard handle number 0). 

If F is a text file, F becomes read-only. After a call to Reset, Eof(F) is True if 
the file is empty; otherwise, EofiF) is False. 

If F is an untyped file, RecSize specifies the record size to be used in data 
transfers. If RecSize is omitted, a default record size of 128 bytes is 
assumed. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Append, Assign, Close, Rewrite, Truncate 

function FileExists (FileName : String): Boolean; 

{ Boolean function that returns True if the file exists; otherwise, it returns 

False. Closes the file if it exists. } 
var 

F: file; 
begin 

{$1-} 

Assign (F, FileName); 

Reset (F) ; 

Close (F) ; 

{$1+} 

FileExists := (IOResult = 0) and (FileName <> "); 
end; { FileExists } 
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begin 

if FileExists (ParamStr (1) ) then 
Writeln('File exists') 



{ Get file name from command line } 
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else 

Writeln('File not found'); 
end. 

RestoreCrtMode procedure Graph 

Function Restores the screen mode to its original state before graphics was 
initialized. 

Declaration RestoreCrtMode 

Remarks Restores the original video mode detected by InitGraph. Can be used in 

conjunction with SetGraphMode to switch back and forth between text and 
graphics modes. 

Restrictions Must be in graphics mode. 

See also CloseGraph, DetectGraph, GetGraphMode, InitGraph, SetGraphMode 

Example uses Graph; 
var 

Gd, Gm: Integer; 

Mode: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt (1) ; 

OutText('<ENTER> to leave graphics:'); 

Readln; 

RestoreCrtMode; 

Writeln('Now in text mode'); 

Write ('<ENTER> to enter graphics mode:'); 

Readln; 

SetGraphMode (GetGraphMode) ; 

OutTextXY(0, 0, 'Back in graphics mode'); 

OutTextXY(0, TextHeight ('H' ) , '<ENTER> to quit:'); 

Readln; 

CloseGraph; 
end. 
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Rewrite procedure 



Function Creates and opens a new file. 

Declaration Rewrite (var F [: file; RecSize: Word ] ) 

Remarks F is a file variable of any file type, which must have been associated with 
an external file using Assign. RecSize is an optional expression of type 
Word, which can only be specified if F is an untyped file. 

Rewrite creates a new external file with the name assigned to F. If an 
external file with the same name already exists, it is deleted and a new 
empty file is created in its place. If F was already open, it is first closed 
and then re-created. The current file position is set to the beginning of the 
empty file. 

If F was assigned an empty name, such as Assign(F, "), then after the call 
to Rewrite, F will refer to the standard output file (standard handle 
number 1). 

If F is a text file, F becomes write-only. After a call to Rewrite, Eof(F) is 
always True. 

If F is an untyped file, RecSize specifies the record size to be used in data 
transfers. If RecSize is omitted, a default record size of 128 bytes is 
assumed. 

With {$1-}, lOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

See also Append, Assign, Reset, Truncate 

Example var F: Tex t ; 
begin 

Assign (F, 'NEWFILE.$$$') ; 
Rewrite (F); 

Writeln(F, 'Just created file with this text in it...'); 
Close (F) ; 
end. 
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RmDir procedure 



Function Removes an empty subdirectory. 

Declaration RmDir (S: String) 

Remarks S is a string-type expression. The subdirectory with the path specified by 
S is removed. If the path does not exist, is non-empty, or is the currently 
logged directory, an I/O error will occur. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

See also MkDir, ChDir, GetDir 

Example begin 

{$1-} 

{ Get directory name from command line } 
RmDir (ParamStr (1) ) ; 
if IOResult <> then 

WritelnC Cannot remove directory') 
else 

Writeln ( ' directory removed' ) ; 
end. 



Round function 



Function Rounds a real-type value to an integer-type value. 

Declaration Round (X: Real) 
Result type Longint 

Remarks X is a real-type expression. Round returns a Longint value that is the value 
of X rounded to the nearest whole number. If X is exactly halfway 
between two whole numbers, the result is the number with the greatest 
absolute magnitude. A run-time error occurs if the rounded value of X is 
not within the Longint range. 

See also Int, Trunc 
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RunError procedure 



Function Stops program execution and generates a run-time error. 

Declaration RunError [ ( ErrorCode: Byte ) ] 

Remarks The RunError procedure corresponds to the Halt procedure except that in 
addition to stopping the program, it generates a run-time error at the 
current statement. ErrorCode is the run-time error number (0 if omitted). If 
the current module is compiled with Debug Information checked (turned 
on), and you're running the program from the IDE, Turbo Pascal auto- 
matically takes you to the RunError call, just as if an ordinary run-time 
error had occurred. 

See also Exit, Halt 

Example {$IFDEF Debug} 

if P = nil then 

RunError (204); 
{$ENDIF} 



Sector procedure 



Graph 



Function Draws and fills an elliptical sector. 

Declaration Sector (X, Y: Integer; StAngle, EndAngle, XRadius, YRadius: Word) 

Remarks Using (X, Y) as the center point, XRadius and YRadius specify the 

horizontal and vertical radii, respectively; Sector draws from StAngle to 
EndAngle. The sector is outlined using the current color, and filled using 
the pattern and color defined by SetFillStyle or SetFillPattern. 

A start angle of and an end angle of 360 will draw and fill a complete 
ellipse. The angles for Arc, Ellipse, FillEllipse, PieSlice, and Sector are 
counterclockwise with degrees at 3 o'clock, 90 degrees at 12 o'clock, and 
soon. 

If an error occurs while filling the sector, GraphResult returns a value of -6 
(grNoScanMem). 

Restrictions Must be in graphics mode. 

See also Arc, Circle, Ellipse, FillEllipse, GetArcCoords, GetAspectRatio, PieSlice, 
SetFillStyle, SetFillPattern, SetGraphBufSize 
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Example use s Graph; 
const 

R = 50; 
var 

Driver, Mode: Integer; 

Xasp, Yasp: Word; 
begin 

Driver := Detect; 

InitGraph (Driver, Mode, " ) ; 

xf GraphResult < then 
Halt(l); 

Sector (GetMaxX div 2, GetMaxY div 2, 0, 45, R, R) ; 

GetAspectRatio (Xasp, Yasp) ; 

Sector (GetMaxX div 2, GetMaxY div 2, 
180, 135, 
R, R * Longint (Xasp) div Yasp) ; 

Readln; 

CloseGraph; 
end. 



{ Put in graphics mode } 



{ Draw circular sector } 

{ Center point } 

{ Mirror angle above } 

{ Circular } 



Seek procedure 



Function Moves the current position of a file to a specified component. 

Declaration Seek (var F; N: Longint) 

Remarks F is any file variable type except text, and N is an expression of type 

Longint. The current file position of F is moved to component number N. 
The number of the first component of a file is 0. In order to expand a file, it 
is possible to seek one component beyond the last component;" that is, the 
statement Seek(F, FileSizeiF)) moves the current file position to the end of 
the file. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Restrictions Cannot be used on text files. File must be open. 

See also FilePos 
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SeekEof function 



Function Returns the end-of-file status of a file. 

Declaration SeekEof [ (var F: Text) 

Result type Boolean 

Remarks SeekEof corresponds to Eof except that it skips all blanks, tabs, and end-of- 
line markers before returning the end-of-file status. This is useful when 
reading numeric values from a text file. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Restrictions Can only be used on text files. File must be open. 

See also Eof, SeekEoln 



SeekEoln function 



Function Returns the end-of-line status of a file. 

Declaration SeekEoln [ (var F: Text) ] 

Result type Boolean 

Remarks SeekEoln corresponds to Eoln except that it skips all blanks and tabs before 
returning the end-of-line status. This is useful when reading numeric 
values from a text file. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

Restrictions Can only be used on text files. File must be open. 

See also Eoln, SeekEof 
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Seg function 



Function Returns the segment of a specified object. 
Declaration Seg(X) 
Result type Word 

Remarks X is any variable, or a procedure or function identifier. The result, of type 
Word, is the segment part of the address of X. 



See also Addr, Ofs 



SetActivePage procedure 



Graph 



Function Set the active page for graphics output. 

Declaration Set ActivePage (Page: Word) 

Remarks Makes Page the active graphics page. All graphics output will now be 
directed to Page. 

Multiple pages are only supported by the EGA (256K), VGA, and 
Hercules graphics cards. With multiple graphics pages, a program can 
direct graphics output to an off-screen page, then quickly display the off- 
screen image by changing the visual page with the SetVisualPage 
procedure. This technique is especially useful for animation. 

Restrictions Must be in graphics mode. 

See also SetVisualPage 

Example use s Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
if (Gd = HercMono) or (Gd = EGA) or (Gd = EGA64) or (Gd = VGA) then 
begin 

SetVisualPage (0) ; 

SetActivePage (1); 

Rectangle (10, 20, 30, 40); 

SetVisualPage (1); 
end 
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else 

OutText('No paging supported.'); 
Readln; 
CloseGraph; 
end. 



SetAIIPalette procedure 



Graph 



Function Changes all palette colors as specified. 

Declaration SetAIIPalette (var Palette) 

Remarks Palette is an untyped parameter. The first byte is the length of the palette. 
The next n bytes will replace the current palette colors. Each color may 
range from -1 to 15. A value of -1 will not change the previous entry's 
value. 

Note that valid colors depend on the current graphics driver and current 
graphics mode. 

If invalid input is passed to SetAIIPalette, GraphResult returns a value of 
-11 (grError), and no changes to the palette settings will occur. 

Changes made to the palette are seen immediately on the screen. In the 
example listed here, several lines are drawn on the screen, then the palette 
is changed. Each time a palette color is changed, all occurrences of that 
color on the screen will be changed to the new color value. 

The following types and constants are defined: 



Black 


= 


Blue 


= 1 


Green 


= 2 


Cyan 


= 3 


Red 


= 4 


Magenta 


= 5 


Brown 


= 6 


LightGray 


= 7 


DarkGray 


= 8 


LightBlue 


= 9 


LightGreen 


= 10 


LightCyan 


= 11 


LightRed 


= 12 


LightMagenta 


= 13 


Yellow 


= 14 


White 


= 15 
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MaxColors =15; 
type 
PaletteType = record 

Size: Byte; 

Colors: array [ 0. . .MaxColors] of Shortint; 
end; 

Restrictions Must be in graphics mode, and can only be used with EGA, EGA 64, or 
VGA (not the IBM 8514 or the VGA in 256-color mode). 

See also GetBkColor, GetColor, GetPalette, GraphResult, SetBkColor, SetColor, 
SetPalette, SetRGBPalette 

Example uses Graph; 
var 

Gd, Gm: Integer; 
Palette: PaletteType; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 

Halt UK- 
Line (0, 0, GetMaxX, GetMaxY) ; 
with Palette do 
begin 

Size := 4; 

Colors [0] := 5 

Colors [1] := 3 

Colors [2] := 1 

Colors [3] := 2 

SetAIIPalette (Palette) ; 
end; 
Readln; 
CloseGraph; 
end. 



SetAspectRatio procedure 



Graph 



Function Changes the default aspect-ratio correction factor. 

Declaration SetAspectRatio (Xasp, Yasp: Word) 

Result type Word 

Remarks SetAspectRatio is used to change the default aspect ratio of the current 
graphics mode. The aspect ratio is used to draw round circles. If circles 
appear elliptical, the monitor is not aligned properly. This can be 
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corrected in the hardware by realigning the monitor, or can be corrected 
in the software by changing the aspect ratio using SetAspectRatio. To read 
the current aspect ratio from the system, use GetAspectRatio. 

Restrictions Must be in graphics mode. 

See also GetAspectRatio 

Example uses Crt , Graph; 
const 

R = 50; 
var 

Driver, Mode: Integer; 
Xasp, Yasp: Word; 
begin 

DirectVideo := False; 

Driver := Detect; { Put in graphics mode } 

InitGraph (Driver, Mode, "); 

if GraphResult < then 

Halt(l); 
GetAspectRatio (Xasp, Yasp) ; { Get default aspect ratio } 

if Xasp = Yasp then 
{ Adjust for VGA and 8514. They have 1:1 aspect } 

Yasp := 5 * Xasp; 
while (Xasp < Yasp) and not KeyPressed do 
{ Keep modifying aspect ratio until 1:1 or key is pressed } 
begin 

SetAspectRatio (Xasp, Yasp) ; 

Circle (GetMaxX div 2, GetMaxY div 2, R) ; 

Inc(Xasp, 20); 
end; 

SetTextJustify (CenterText, CenterText) ; 
OutTextXY (GetMaxX div 2, GetMaxY div 2, 'Done!'); 
Readln; 
CloseGraph; 
end. 



SetBkColor procedure 



Graph 



Function Sets the current background color using the palette. 

Declaration SetBkColor (ColorNum: Word) 

Remarks Background colors may range from to 15, depending on the current 

graphics driver and current graphics mode. On a CGA, SetBkColor sets the 
flood overscan color. 
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SetBkColoriN) makes the Nth color in the palette the new background 
color. The only exception is SetBkColor(O), which always sets the 
background color to black. 

Restrictions Must be in graphics mode. 

See also GetBkColor, GetColor, GetPalette, SetAUPalette, SetColor, SetPalette, 
SetRGBPalette 

Example uses C rt, Graph; 
var 

GraphDriver, GraphMode: Integer; 
Palette: PaletteType; 
begin 

GraphDriver := Detect; 

InitGraph (GraphDriver, GraphMode, " ) ; 

Randomize; 

if GraphResult <> grOk then 

Halt(l); 
GetPalette (Palette) ; 
repeat 

if Palette. Size <> 1 then 
SetBkColor (Random (Palette. Size) ) ; 

LineTo (Random (GetMaxX) , Random (GetMaxY) ) ; 
until KeyPressed; 
CloseGraph; 
end. 



SetCBreak procedure 



Dos 



Function Sets the state of Ctrl-Break checking in DOS. 

Declaration SetCBreak (Break: Boolean) 

Remarks SetCBreak sets the state of Ctrl-Break checking in DOS. When off (False), 

DOS only checks for Ctrl-Break during I/O to console, printer, or communi- 
cation devices. When on (True), checks are made at every system call. 

See also GetCBreak 
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SetColor procedure 



Graph 



Function Sets the current drawing color using the palette. 

Declaration SetColor (Color: Word) 

Remarks SetColor(5) makes the fifth color in the palette the current drawing color. 
Drawing colors may range from to 15, depending on the current 
graphics driver and current graphics mode. 

GetMaxColor returns the highest valid color for the current driver and 
mode. 

Restrictions Must be in graphics mode. 

See also DrawPoly, GetBkColor, GetColor, GetMaxColor, GetPalette, GraphResult, 
SetAUPalette, SetBkColor, SetPalette, SetRGBPalette 

Example uses Crt, Graph; 
var 

GraphDriver, GraphMode: Integer; 
begin 

GraphDriver := Detect; 

InitGraph (GraphDriver, GraphMode, "); 

if GraphResult <> grOk then 

Halt(l); 
Randomize; 
repeat 

SetColor (Random (GetMaxColor) + 1); 

LineTo (Random (GetMaxX) , Random (GetMaxY) ) ; 
until KeyPressed; 
end. 



SetDate procedure 



Dos 



Function Sets the current date in the operating system. 

Declaration SetDate (Year, Month, Day: Word) 

Remarks Valid parameter ranges are Year 1980..2099, Month 1..12, and Day 1..31. If 
the date is invalid, the request is ignored. 

See also GetDate, GetTime, SetTime 
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SetFAttr procedure 



Dos 



Function Sets the attributes of a file. 

Declaration SetFAttr (var F; Attr: Word) 

Remarks F must be a file variable (typed, untyped, or text file) that has been 

assigned but not opened. The attribute value is formed by adding the 
appropriate attribute masks defined as constants in the Dos unit. 

const 

Readonly = $01 

Hidden = $02 

SysFile = $04 

Volume ID = $08 

Directory = $10 

Archive = $20 

Errors are reported in DosError, possible error codes are 3 (Invalid Path) 
and 5 (File Access Denied). 

Restrictions F cannot be open. 

See also GetFAttr, GetFTime, SetFTime 

Example uses dos; 
var 

F: file; 
begin 

Assign (F, 'C:\AUTOEXEC.BAT'); 

SetFAttr (F, Hidden); { Uh-oh } 

Readln; 

SetFAttr (F, Archive); { Whew! } 

end. 



SetFillPattem procedure 



Graph 



Function Selects a user-defined fill pattern. 

Declaration SetFillPattem (Pattern: FillPatternType; Color: Word) 

Remarks Sets the pattern and color for all filling done by FillPoly, FloodFill, Bar, 
Bar3D, and PieSlice to the bit pattern specified in Pattern and the color 
specified by Color. If invalid input is passed to SetFillPattem, GraphResult 
returns a value of -11 (grError), and the current fill settings will be 
unchanged. FillPatternType is predefined as follows: 
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type 

FillPatternType = array [1.. 8] of Byte; 

The fill pattern is based on the underlying Byte values contained in the 
Pattern array. The pattern array is 8 bytes long with each byte corre- 
sponding to 8 pixels in the pattern. Whenever a bit in a pattern byte is 
valued at 1, a pixel will be plotted. For example, the following pattern 
represents a checkerboard (50% gray scale): 



Binary 


Hex 




10101010 


$AA 


(lstty'te) 


01010101 


$55 


(2nd ty'te) 


10101010 


$AA 


(3rd ty'te) 


01010101 


$55 


(4thtyte) 


10101010 


$AA 


(5thb?'te) 


01010101 


$55 


(6thb?'te) 


10101010 


$AA 


(7thh?'te) 


01010101 


$55 


(8thb?'te) 



User-defined fill patterns enable you to create patterns different from the 
predefined fill patterns that can be selected with the SetFillStyle 
procedure. Whenever you select a new fill pattern with SetFillPattern or 
SetFillStyle, all fill operations will use that fill pattern. Calling SetFillStyle 
(UserField, SomeColor) will always select the user-defined pattern. This lets 
you define and use a new pattern using SetFillPattern, then switch 
between your pattern and the built-ins by making calls to SetTextStyle. 

Restrictions Must be in graphics mode. 

See also Bar, Bar3D, FillPoly, GetFillPattern, GetFillSettings, GraphResult, PieSlice 

Example uses Gr aph ; 
const 

Gray50: FillPatternType = ($AA, $55, $AA, $55, $AA, $55, $M, $55); 
var 

Gd, Gra: Integer; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

SetFillPattern (Gray50, White); 

Bar(0, 0, 100, 100); { Draw a bar in a 50% gray scale } 

Readln; 

CloseGraph; 
end. 
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SetFillStyle procedure 



Graph 



Function Sets the fill pattern and color. 

Declaration SetFillStyle (Pattern: Word; Color: Word) 

Remarks Sets the pattern and color for all filling done by FillPoly, Bar, Bar3D, and 

PieSlice. A variety of fill patterns are available. The default pattern is solid, 
and the default color is the maximum color in the palette. If invalid input 
is passed to SetFillStyle, GraphResult returns a value of -11 (grError), and 
the current fill settings will be unchanged. The following constants are 
defined: 

const 

{ Fill patterns for Get/SetFillStyle: } 

{ Fills area in background color 

{ Fills area in solid fill color 

{ — fill 

{ /// fill 

{ /// fill with thick lines 

{ \\\ fill with thick lines 

{ \\\ fill 

{ Light hatch fill 

{ Heavy cross hatch fill 

{ Interleaving line fill 

{ Widely spaced dot fill 

{ Closely spaced dot fill 

{ User-defined fill 

If Pattern equals UserFill, the user-defined pattern (set by a call to 
SetFillPattern) becomes the active pattern. 



EmptyFill 


= 0; 


SolidFill 


= 1; 


LineFill 


= 2; 


LtSlashFill 


= 3; 


SlashFill 


= 4; 


BkSlashFill 


= 5; 


LtBkSlashFill 


= 6; 


HatchFill 


= 7; 


XHatchFill 


= 8; 


InterleaveFill 


= 9; 


WideDotFill 


= 10 


CloseDotFill 


= 11 


UserFill 


= 12 



Restrictions Must be in graphics mode. 



See also 
Example 



Bar, Bar3D, FillPoly, GetFillSettings, PieSlice, GetMaxColor, GraphResult 



uses Graph; 
var 

Gm, Gd: Integer; 
begin 

Gd := Detect; 
InitGraph(Gd, Gm, "); 
SetFillStyle (SolidFill, 0); 
Bar(0, 0, 50, 50); 
SetFillStyle (XHatchFill, 1) ; 
Bar (60, 0, 110, 50); 
Readln; 
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CloseGraph; 
end. 



SetFTime procedure 



Dos 



Function Sets the date and time a file was last written. 

Declaration SetFTime (var F; Time: Longint) 

Remarks F must be a file variable (typed, untyped, or text file) that has been 

assigned and opened. The Time parameter can be created through a call to 
PackTime. Errors are reported in DosError, the only possible error code is 6 
(Invalid File Handle). 

Restrictions F must be open. 

See also GetFTime, PackTime, SetFAttr, UnpackTime 



SetGraphBufSize procedure 



Graph 



Function Allows you to change the size of the buffer used for scan and flood fills. 

Declaration SetGraphBuf Size (Buf Size: Word); 

Remarks The internal buffer size is set to Buf Size, and a buffer is allocated on the 
heap when a call is made to InitGraph. 

The default buffer size is 4K, which is large enough to fill a polygon with 
about 650 vertices. Under rare circumstances, enlarging the buffer may be 
necessary in order to avoid a buffer overflow. 

Restrictions Note that once a call to InitGraph has been made, calls to SetGraphBufSize 
are ignored. 

See also FloodFill, FillPoly, InitGraph 
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SetGraphMode procedure 



Graph 



Function Sets the system to graphics mode and clears the screen. 

Declaration SetGraphMode (Mode: Integer) 

Remarks Mode must be a valid mode for the current device driver. SetGraphMode is 
used to select a graphics mode different than the default one set by 
InitGraph. 

SetGraphMode can also be used in conjunction with RestoreCrtMode to 
switch back and forth between text and graphics modes. 

SetGraphMode resets all graphics settings to their defaults (current pointer, 
palette, color, viewport, and so forth). 

GetModeRange returns the lowest and highest valid modes for the current 
driver. 

If an attempt is made to select an invalid mode for the current device 
driver, GraphResult returns a value of -10 (grlnvalidMode). 

The following constants are defined: 



Graphics 
driver 


Graphics 
modes 


Value 


Column 
xrow 


Palette 


Pages 


CGA 


CGACO 
CGAC1 
CGAC2 
CGAC3 
CGAHi 



1 
2 
3 

4 


320x200 
320x200 
320x200 
320x200 
640x200 


CO 
CI 
C2 
C3 
2 color 


1 
1 
1 
1 
1 


MCGA 


MCGACO 

MCGACl 

MCGAC2 

MCGAC3 

MCGAMed 

MCGAHi 



1 
2 
3 
4 
5 


320x200 
320x200 
320x200 
320x200 
640x200 
640x480 


CO 

CI 

C2 

C3 
2 color 
2 color 


1 
1 
1 
1 
1 
1 


EGA 


EGALo 
EGAHi 



1 


640x200 
640x350 


16 color 
16 color 


4 
2 


EGA64 


EGA64Lo 
EGA64H1 




1 


640x200 
640x350 


16 color 
4 color 


1 
1 


EGA-MONO 


EGAMonoHi 
EGAMonoHi 


3 
3 


640x350 
640x350 


2 color 
2 color 


1* 
2** 


HERC 


HercMonoHi 





720x348 


2 color 


2 


ATT400 


ATT400C0 
ATT400C1 
ATT400C2 



1 
2 


320x200 
320x200 
320x200 


CO 
CI 
C2 


1 
1 
1 
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Graphics Graphics 
driver modes 


Value 


Column 
xrow 


Palette 


Pages 


ATT400C3 

ATT400Med 

ATT400H1 


3 

4 
5 


320x200 
640x200 
640x400 


C3 
2 color 
2 color 


1 
1 
1 


VGA VGALo 
VGAMed 
VGAHi 



1 
2 


640x200 
640x350 
640x480 


16 color 
16 color 
16 color 


2 
2 
1 


PC3270 PC3270Hi 





720x350 


2 color 


1 


514 IBM8514Lo 
8514 IBM8514Hi 






640x480 
1024x768 


256 color 
256 color 


1 
1 


* 64K on EGAMono card 
" 256K on EGAMono card 











Restrictions A successful call to InitGraph must have been made before calling this 
routine. 

See also ClearDevice, CloseGraph, DetectGraph, GetGraphMode, GetModeRange, 
GraphResult, InitGraph, RestoreCrtMode 

Example uses Graph; 
var 

GraphDriver: Integer; 

GraphMode: Integer; 

LowMode: Integer; 

HighMode: Integer; 
begin 

GraphDriver := Detect; 

InitGraph (GraphDriver, GraphMode, "); 

if GraphResult <> grOk then 
Halt(l); 

GetModeRange (GraphDriver, LowMode, HighMode); 

SetGraphMode (LowMode) ; 

Line(0, 0, GetMaxX, GetMaxY) ; 

Readln; 

CloseGraph; 
end. 



{ Select low-resolution mode } 
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SetlntVec procedure 



Dos 



Function Sets a specified interrupt vector to a specified address. 

Declaration SetIntVec(IntNo: Byte; Vector: Pointer) 

Remarks IntNo specifies the interrupt vector number (0..255), and Vector specifies 

the address. Vector is often constructed with the @ operator to produce the 
address of an interrupt procedure. Assuming IntlBSave is a variable of 
type Pointer, and IntlBHandler is an interrupt procedure identifier, the 
following statement sequence installs a new interrupt $1B handler and 
later restores the original handler: 

GetIntVec($lB, IntlBSave); 
SetlntVec ($1B, @IntlBHandler) ; 



SetlntVec ($1B, IntlBSave); 

See also GetlntVec 

SetLineStyle procedure 



Graph 



Function Sets the current line width and style. 

Declaration SetLineStyle(LineStyle: Word; Pattern: Word; Thickness: Word) 

Remarks Affects all lines drawn by Line, LineTo, Rectangle, DrawPoly, Arc, and so on. 
Lines can be drawn solid, dotted, centerline, or dashed. If invalid input is 
passed to SetLineStyle, GraphResult returns a value of -11 (grError), and the 
current line settings will be unchanged. The following constants are 
declared: 



const 






SolidLn 


= 





DottedLn 


= 


1 


CenterLn 


= 


2 


DashedLn 


= 


3 


UserBitLn 


= 


4 


NormWidth 


= 


1 


ThickWidth 


= 


3 



{ User-defined line style } 



LineStyle is a value from SolidLn to UserBitLn(O.A), Pattern is ignored 
unless LineStyle equals UserBitLn, and Thickness is NormWidth or 
ThickWidth. When LineStyle equals UserBitLn, the line is output using the 
16-bit pattern defined by the Pattern parameter. For example, if Pattern = 
$AAAA, then the 16-bit pattern looks like this: 
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1010101010101010 

1010101010101010 
1010101010101010 
1010101010101010 



{ NormWidth } 
{ ThickWidth } 



Restrictions Must be in graphics mode. 

See also DrawPoly, GetLineSettings, GraphResult, Line, LineRel, LineTo, SetWriteMode 

Example U ses Graph; 
var 

Gd, Gm: Integer; 

XI, Yl, X2, Y2: Integer; 
begin 

Gd := Detect; 

InitGraph(Gd, Gm, "); 

if GraphResult <> grOk then 
Halt(l); 

XI := 10; 

Yl := 10; 

X2 := 200; 

Y2 := 150; 

SetLineStyle (DottedLn, 0, NormWidth); 

Rectangle (XI, Yl, X2, Y2) ; 

SetLineStyle (UserBitLn, $C3, ThickWidth); 

Rectangle (Pred (XI), Pred(Yl), Succ(X2), Succ(Y2)); 

Readln; 

CloseGraph; 
end. 



SetPalette procedure 



Graph 



Function Changes one palette color as specified by ColorNum and Color. 

Declaration SetPalette (ColorNum: Word; Color: Shortint) 

Remarks Changes the ColorNum entry in the palette to Color. SetPalette(0, LightCyan) 
makes the first color in the palette light cyan. ColorNum may range from 
to 15, depending on the current graphics driver and current graphics 
mode. If invalid input is passed to SetPalette, GraphResult returns a value 
of -11 (grError), and the palette will be unchanged. 

Changes made to the palette are seen immediately on the screen. In the 
example here, several lines are drawn on the screen, then the palette is 
changed randomly. Each time a palette color is changed, all occurrences of 
that color on the screen will be changed to the new color value. 
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The following constants are defined: 

const 

Black = 

Blue = 1 

Green = 2 

Cyan = 3 

Red = 4 

Magenta = 5 

Brown = 6 

LightGray = 7 

DarkGray = 8 

LightBlue = 9 

. LightGreen = 10 

Light Cyan =11 

LightRed = 12 

LightMagenta = 13 

Yellow = 14 

White = 15 

Restrictions Must be in graphics mode, and can only be used with EGA, EGA 64, or 
VGA (not the IBM 8514 or the VGA in 256-color mode). 

See also GetBkColor, GetColor, GetPalette, GraphResult, Set AllP alette, SetBkColor, 
SetColor, SetRGBPalette 

Example uses Crt, Graph; 
var 

GraphDriver, GraphMode: Integer; 
Color: Word; 
Palette: PaletteType; 
begin 

GraphDriver := Detect; 

InitGraph (GraphDriver, GraphMode, "); 

if GraphResult <> grOk then 

Halt(l); 
GetPalette (Palette); 
if Palette. Size <> 1 then 
begin 

for Color := to Pred(Palette.Size) do 

begin 

SetColor (Color) ; 

Line(0, Color * 5, 100, Color * 5); 

end; 

Randomize; 

repeat 

SetPalette (Random (Palette . Size) , Random (Palette . Size) ) ; 

until KeyPressed; 
end 
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else 

Line(0 ; 0, 100, 0); 
Readln; 
CloseGraph; 
end. 



SetRGBPalette procedure 



Graph 



Function Modifies palette entries for the IBM 8514 and VGA drivers. 

Declaration SetRGBPalette (ColorNum, RedValue, GreenValue, BlueValue: Integer) 

Remarks ColorNum defines the palette entry to be loaded, while RedValue, 

GreenValue, and BlueValue define the component colors of the palette 
entry. 

For the IBM 8514 display, ColorNum is in the range 0..255. For the VGA in 
256K color mode, ColorNum is the range 0..15. Only the lower byte of 
RedValue, GreenValue or BlueValue is used, and out of this byte, only the 6 
most-significant bits are loaded in the palette. 

C^> For compatibility with other IBM graphics adapters, the BGI driver 

defines the first 16 palette entries of the IBM 8514 to the default colors of 
the EGA/ VGA. These values can be used as is, or they can be changed by 
using SetRGBPalette. 

Restrictions SetRGBPalette can only be used with the IBM 8514 driver and the VGA. 

See also GetBkColor, GetColor, GetPalette, GraphResult, Set AllP alette, SetBkColor, 
SetColor, SetPalette 

Example uses Graph; 
type 
RGBRec = record 

RedVal, GreenVal, BlueVal: Integer; 
end; 
const 
EGAColors: array [ 0. .MaxColors] of RGBRec = 

( {NAME 

(RedVal:$00;GreenVal:$00;BlueVal:$00) , {Black 

(RedVal:$00;GreenVal:$00;BlueVal:$FC) , {Blue 

(RedVal:$24;GreenVal:$fc;BlueVal:$24) , {Green 

(RedVal:$00;GreenVal:$fc;BlueVal:$FC) , {Cyan 

(RedVal:$FC;GreenVal:$14;BlueVal:$14),{Red 

(RedVal:$BO;GreenVal:$00;BlueVal:$FC) , {Magenta 

(RedVal:$70;GreenVal:$48;BlueVal:$00), {Brown 

(RedVal:$C4;GreenVal:$C4;BlueVal:$C4) , {White 



COLOR) 


EGA 


0} 


EGA 


1} 


EGA 


2} 


EGA 


3} 


EGA 


4} 


EGA 


5} 


EGA 20} 


EGA 


7} 
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(RedVal:$34;GreenVal:$34;BlueVal:$34),{Gray EGA 56} 

(RedVal:$00;GreenVal:$00;BlueVal:$70),{Lt Blue EGA 57} 

(RedVal:$00;GreenVal:$70;BlueVal:$00),{Lt Green EGA 58} 

(RedVal:$00;GreenVal:$70;BlueVal:$70),{Lt Cyan EGA 59} 

(RedVal:$70;GreenVal:$00;BlueVal:$00),{Lt Red EGA 60} 

(RedVal:$70;GreenVal:$00;BlueVal:$70),{Lt Magenta EGA 61} 

(RedVal:$FC;GreenVal:$fc;BlueVal:$24), {Yellow EGA 62} 

(RedVal:$FC;GreenVal:$fc;BlueVal:$FC) {Br. White EGA 63} 

); 
var 

Driver, Mode, I: Integer; 
begin 
Driver := IBM8514; { Override detection } 

Mode := IBM8514Hi; 

InitGraph (Driver, Mode, "); { Put in graphics mode } 

if GraphResult < then 

Halt(l); 
{ Zero palette, make all graphics output invisible } 
for I := to MaxColors do 

with EGAColorsfl] do 

SetRGBPalette (I, 0, 0, 0); 
{ Display something } 
{ Change first 16 8514 palette entries } 
for I := 1 to MaxColors do 
begin 

SetColor(I); 

OutTextXYUO, I * 10, ' ..Press any key.. '); 
end; 

{ Restore default EGA colors to 8514 palette } 
for I := to MaxColors do 

with EGAColorsfl] do 
SetRGBPalette (I, RedVal, GreenVal, BlueVal) ; 
Readln; 
CloseGraph; 
end. 



SetTextBuf procedure 



Function Assigns an I/O buffer to a text file. 

Declaration SetTextBuf (var F: Text; var Buf [ ; Size: Word ] ) 

Remarks F is a text-file variable, Buf is any variable, and Size is an optional 
expression of type Word. 

Each text-file variable has an internal 128-byte buffer that, by default, is 
used to buffer Read and Write operations. This buffer is adequate for most 
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Example 



SetTextBuf procedure 



applications. However, heavily I/O-bound programs, such as applications 
that copy or convert text files, will benefit from a larger buffer, because it 
reduces disk head movement and file system overhead. 

SetText Buf changes the text file F to use the buffer specified by Buf instead 
of F's internal buffer. Size specifies the size of the buffer in bytes. If Size is 
omitted, SizeOf(Buf) is assumed; that is, by default, the entire memory 
region occupied by Buf is used as a buffer. The new buffer remains in 
effect until F is next passed to Assign. 

SetTextBuf should never be applied to an open file, although it can be 
called immediately after Reset, Rewrite, and Append. Calling SetTextBuf on 
an open file once I/O operations has taken place can cause loss of data 
because of the change of buffer. 

Turbo Pascal doesn't ensure that the buffer exists for the entire duration of 
I/O operations on the file. In particular, a common error is to install a 
local variable as a buffer, and then use the file outside the procedure that 
declared the buffer. 

var 

F: Text; 

Ch: Char; 

Buf: array[l.. 10240] of Char; { 10K buffer } 

begin 

{ Get file to read from command line } 

Assign (F, ParamStr(l)) ; 

{ Bigger buffer for faster reads } 

SetTextBuf (F, Buf ) ; 

Reset (F); 

{ Dump text file onto screen } 

while not Eof (f) do 

begin 

Read(F, Ch) ; 
Write (Ch) ; 

end; 
end. 
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SetTextJustify procedure 



Graph 



Function Sets text justification values used by OutText and OutTextXY. 

Declaration SetTextJustify (Horiz, Vert: Word) 

Remarks Text output after a SetTextJustify will be justified around the current 
pointer in the manner specified. Given the following: 

SetTextJustify (CenterText, CenterText) ; 
OutTextXY (100, 100, 'ABC'); 

The point(100, 100) will appear in the middle of the letter B. The default 
justification settings can be restored by SetTextJustify&eftText, TopText). If 
invalid input is passed to SetTextJustify, GraphResult returns a value of -11 
(grError), and the current text justification settings will be unchanged. 



The following constants are defined: 



const 

LeftText = 
CenterText = 1 
RightText = 2 
BottomText = 
CenterText = 1 
TopText = 2 



{ Horizontal justification } 



{ Vertical justification } 
{ Not declared twice } 



Restrictions Must be in graphics mode. 

See also GetTextSettings, GraphResult, OutText, OutTextXY, SetLineStyle, 
SetUserCharSize, TextHeight, TextWidth 

Example uses Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 
Halt (1) ; 

{ Center text onscreen } 

SetTextJustify (CenterText, CenterText) ; 

OutTextXY (Succ (GetMaxX) div 2, Succ (GetMaxY) diy 2, 'Easily Centered') ; 

Readln; 

CloseGraph; 
end. 
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SetTextStyle procedure 



Graph 



Function Sets the current text font, style, and character magnification factor. 

Declaration SetTextStyle(Font: Word; Direction: Word; CharSize: Word) 

Remarks Affects all text output by OutText and OutTextXY. One 8x8 bit-mapped 

font and several stroked fonts are available. Font directions supported are 
normal (left to right) and vertical (90 degrees to normal text, starts at the 
bottom and goes up). The size of each character can be magnified using 
the CharSize factor. A CharSize value of one will display the 8x8 bit- 
mapped font in an 8x8 pixel rectangle on the screen, a CharSize value 
equal to 2 will display the 8x8 bit-mapped font in a 16x16 pixel rectangle 
and so on (up to a limit of 10 times the normal size). Always use 
TextHeight and TexiWidth to determine the actual dimensions of the text. 

The normal size values for text are 1 for the default font and 4 for a 
stroked font. These are the values that should be passed as the CharSize 
parameter to SetTextStyle. SetUserCharSize can be used to customize the 
dimensions of stroked font text. 

Normally, stroked fonts are loaded from disk onto the heap when a call is 
made to SetTextStyle. However, you can load the fonts yourself or link 
them directly to your .EXE file. In either case, use RegisterBGIfont to 
register the font with the Graph unit. 

When stroked fonts are loaded from disk, errors can occur when trying to 
load them. If an error occurs, GraphResult returns one of the following 
values: 

-8 Font file not found 

-9 Not enough memory to load the font selected 

-11 Graphics error 

-12 Graphics I/O error 

-13 Invalid font file 

-14 Invalid font number 

The following type and constants are declared: 



a 



const 

DefaultFont 

TriplexFont 

SmallFont 

SansSerifFont 

GothicFont 



8x8 bit-mapped font } 
{ Stroked fonts } 
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HorizDir 
VertDir 



= 0; 
= 1; 



{ Left to right } 
{ Bottom to top } 



Restrictions Must be in graphics mode. 



See also GetTextSettings, GraphResult, OutText, OutTextXY, RegisterBGIfont, 
SetText Justify, SetUserCharSize, TextHeight, TextWidth 

Example use s Graph; 
var 

Gd, Gm: Integer; 
Y, Size: Integer; 
begin 
Gd := Detect; 
InitGraph (Gd, Gm, " ) ; 
if GraphResult <> grOk then 

Halt(l); 
Y := 0; 

for Size := 1 to 4 do 
begin 

SetTextStyle (DefaultFont, HorizDir, Size) ; 

OutTextXY (0, Y, 'Size = ' + Chr(Size .+ 48)); 

Inc(Y, TextHeight ('H') + 1); 
end; 
Readln; 
CloseGraph; 
end. 



SetTime procedure 



Dos 



Function Sets the current time in the operating system. 

Declaration SetTime (Hour, Minute, Second, SeclOO: Word) 

Remarks Valid parameter ranges are Hour 0..23, Minute 0..59, Second 0..59, and 

SeclOO (hundredths of seconds) 0..99. If the time is not valid, the request is 
ignored. 

See also GetDate, GetTime, PackTime, SetDate, UnpackTime 
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SetUserCharSize procedure 



Graph 



Function Allows the user to vary the character width and height for stroked fonts. 

Declaration SetUserCharSize (MultX, DivX, MultY, DivY: Word) 

Remarks MultX:DivX is the ratio multiplied by the normal width for the active font; 
MultYiDivY is the ratio multiplied by the normal height for the active font. 
In order to make text twice as wide, for example, use a MultX value of 2, 
and set DivX equal to 1 (2 div 1 = 2). 

You don't have to call SetTextStyle immediately after calling 
SetUserCharSize to make that character size take effect. Calling 
SetUserCharSize sets the current character size to the values given. 

Restrictions Must be in graphics mode. 

See also SetTextStyle, OutText, OutTextXY, TextHeight, TextWidth 

Example The following program shows how to change the height and width of text: 

uses Graph; 
var 

Driver, Mode: Integer; 
begin 

Driver := Detect; 

InitGraph (Driver, Mode, "); 

if GraphResult <> grOk then 
Halt(l); 

{ Showoff } 

SetTextStyle (TriplexFont, HorizDir, 4); 

OutText ('Norm'); 

SetUserCharSize (1, 3, 1, 1) ; 

OutText ('Short '); 

SetUserCharSize (3, 1, 1, 1); 

OutText ('Wide') ; 

Readln; 

CloseGraph; 
end. 
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SetVerify procedure 



Dos 



Function Sets the state of the verify flag in DOS. 

Declaration SetVerify (Verify: Boolean) 

Remarks SetVerify sets the state of the verify flag in DOS. When off (False), disk 
writes are not verified. When on (True), all disk writes are verified to 
ensure proper writing. 

See also GetVerify 



SetViewPort procedure 



Graph 



Function Sets the current output viewport or window for graphics output. 

Declaration SetViewPort(Xl, Yl, X2, Y2: Integer; Clip: Boolean) 

Remarks (XI, Yl) define the upper left corner of the viewport, and (X2, Y2) define 
the lower right corner (0 <=X1<X2 and <= Yl < Yl). The upper left 
corner of a viewport is (0, 0). 

The Boolean variable Clip determines whether drawings are clipped at the 
current viewport boundaries. SetViewPort(Q, 0, GetMaxX, GetMaxY, True) 
always sets the viewport to the entire graphics screen. If invalid input is 
parsed to SetViewPort, GraphResult returns -11 (grError), and the current 
view settings will be unchanged. The following constants are defined: 

const 

ClipOn = True; 
ClipOff = False; 

All graphics commands (for example, GetX, OutText, Rectangle, MoveTo, 
and so on) are viewport-relative. In the example, note that MoveTo moves 
the current pointer to (5, 5) inside the viewport (the absolute coordinates 
would be (15, 25)). 
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(GetMaxX.O) 




(O.Get MaxY) 



(GetMaxX, GetMaxY) 



If the Boolean variable Clip is set to True when a call to SetViewPort is 
made, all drawings will be clipped to the current viewport. Note that the 
"current pointer" is never clipped. The following will not draw the 
complete line requested because the line will be clipped to the current 
viewport: 

SetViewPort (10, 10, 20, 20, ClipOn) ; 
Line(0, 5, 15, 5); 

The line would start at absolute coordinates (10,15) and terminate at 
absolute coordinates (25, 15) if no clipping was performed. But since 
clipping was performed, the actual line that would be drawn would start 
at absolute coordinates (10, 15) and terminate at coordinates (20, 15). 

InitGraph, GraphDefaults, and SetGraphMode all reset the viewport to the 
entire graphics screen. The current viewport settings are available by 
calling the procedure GetViezvSettings, which accepts a parameter of the 
following global type: 

type 

ViewPortType = record 

XI, Yl, X2, Y2: Integer; 

Clip: Boolean; 
end; 

SetViewPort moves the current pointer to (0, 0). 

Restrictions Must be in graphics mode. 

See also ClearViewPort, GetViewSettings, GraphResult 
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SetViewPort procedure 



Example uses Graph; 
var 

Gd, Gm: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
if (Gd = HercMono) or (Gd = EGA) or (Gd = EGA64) or (Gd = VGA) then 
begin 

SetVisualPage (0) ; 

SetActivePage(l); 

Rectangle (10, 20, 30, 40); 

SetVisualPage (1); 
end 
else 

OutText ('No paging supported. ' ) ; 
Readln; 
CloseGraph; 
end. 



SetVisualPage procedure 



Graph 



Function Sets the visual graphics page number. 

Declaration Set VisualPage (Page: Word) 

Remarks Makes Page the visual graphics page. 

Multiple pages are only supported by the EGA (256K), VGA, and 
Hercules graphics cards. With multiple graphics pages, a program can 
direct graphics output to an off-screen page, then quickly display the off- 
screen image by changing the visual page with the SetVisualPage 
procedure. This technique is especially useful for animation. 



fstrictions 


Must be in graphics mode. 


See also 


SetActivePage 


Example 


uses Graph; 




var 




Gd, Gm: Integer; 




begin 




Gd := Detect; 




InitGraph (Gd, Gm, "); 




if GraphResult <> grOk then 




Halt(l); 
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SetVisualPage procedure 



if (Gd = HercMono) or (Gd = EGA) or (Gd = EGA64) or (Gd = VGA) then 
begin 

SetVisualPage (0); 

SetActivePage(l); ■ 

Rectangle (10, 20, 30, 40); 

SetVisualPage (1); 
end 
else 

OutTextfNo paging supported.'); 
Readln; 
CloseGraph; 
end. 



SetWriteMode procedure 



Graph 



Function Sets the writing mode for line drawing. 

Declaration SetWriteMode(WriteMode: Integer) 

Remarks The following constants are defined: 



See also 
Example 



const 

CopyPut = 0; 
XORPut = 1; 



{ MOV } 
{ XOR } 



Each constant corresponds to a binary operation between each byte in the 
line and the corresponding bytes on the screen. CopyPut uses the assembly 
language MOV instruction, overwriting with the line whatever is on the 
screen. XORPut uses the XOR command to combine the line with the 
screen. Two successive XOR commands will erase the line and restore the 
screen to its original appearance. 

SetWriteMode affects calls only to the following routines: DrawPoly, Line, 
LineRel, LineTo, and Rectangle . 

Line, LineTo, Putlmage, SetLineStyle 

uses Crt, Graph; 
var 

Driver, Mode, I: Integer; 
XI, Yl, Dx, Dy: Integer; 
Filllnfo: FillSettingsType; 
begin 

DirectVideo := False; 
Randomize; 
Driver := Detect; 
InitGraph (Driver, Mode, " ) ; 



1 



{ Turn off screen write } 



{ Put in graphics mode } 
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SetWriteMode procedure 



if GraphResult < then 

Halt(l); 
{ Fill screen with background pattern } 
GetFillSettings (Filllnfo) ; 
SetFillStyle (WideDotFill, Filllnfo . Color) ; 
Bar(0, 0, GetMaxX, GetMaxY); 
Dx := GetMaxX div 4; 
Dy := GetMaxY div 4; 
SetLineStyle(SolidLn, 0, ThickWidth) ; 
SetWriteMode(XORPut); 
repeat 

XI := Random (GetMaxX - Dx) ; 

Yl := Random (GetMaxY - Dy) ; 

Rectangle (XI, Yl, XI + Dx, Yl + Dy) ; 

Delay (10); 

Rectangle (XI, Yl, XI + Dx, Yl + Dy) ; 
until KeyPressed; 
Readln; 
CloseGraph; 
end. 



{ Get current settings } 



{ Determine rectangle's dimensions } 



{ XOR mode for rectangle ) 
{ Draw until a key is pressed } 



{ Draw it } 

{ Pause briefly } 

{ Erase it } 



Sin function 



Function Returns the sine of the argument. 
Declaration Sin(X: Real) 

Result type Real 

Remarks X is a real-type expression. The result is the sine of X. X is assumed to 
represent an angle in radians. 

See also ArcTan, Cos 

Example var 

R: Real; 
begin 

R := Sin (Pi); 
end. 
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SizeOf function 



Function Returns the number of bytes occupied by the argument. 
Declaration sizeOf(X) 
Result type Word 

Remarks X is either a variable reference or a type identifier. SizeOf returns the 
number of bytes of memory occupied by X. 

SizeOf should always be used when passing values to FillChar, Move, 
GetMem, and so on: 

FillChar (S, SizeOf (S), 0) ; 
GetMem(P, SizeOf (RecordType) ) ; 

Example type 

CustRec = record 
Name: string [30] ; 
Phone: string [14]; 
end; 
var 

P: A CustRec; 
begin 

GetMem (P, SizeOf (CustRec) ) ; 
end. 



Sound procedure 



Crt 



Function Starts the internal speaker. 

Declaration Sound (Hz: Word) 

Remarks Hz specifies the frequency of the emitted sound in hertz. The speaker 
continues until explicitly turned off by a call to NoSound. 



See also 


NoSound 


Example 


uses Crt; 




begin 




Sound (220) ; 




Delay (200); 




NoSound; 




end. 



1 



{ Beep } 

{ Pause } 

{ Relief! } 
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SPtr function 



SPtr function 



Function Returns the current value of the SP register. 
Declaration SPtr 
Result type Word 

Remarks The result, of type Word, is the offset of the stack pointer within the stack 
segment. 

See also SSeg 



Sqr function 



Function Returns the square of the argument. 

Declaration sqr (X) 

Result type Same type as parameter. 

Remarks X is an integer-type or real-type expression. The result, of the same type 
as X, is the square of X, or X * X. 



Sqrt function 



Function Returns the square root of the argument. 

Declaration Sqrt(X: Real) 

Result type Real 

Remarks X is a real-type expression. The result is the square root of X. 



SSeg function 



Function Returns the current value of the SS register. 

Declaration sseg 

Result type Word 

Remarks The result, of type Word, is the segment address of the stack segment. 

See also SPtr, CSeg, DSeg 
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Str procedure 



Function Converts a numeric value to its string representation. 

Declaration Str(X [: Width [: Decimals ] ]; var S: String) 

Remarks X is an integer-type or real-type expression. Width and Decimals are 

integer-type expressions. S is a string-type variable. Str converts X to its 
string representation, according to the Width and Decimals formatting 
parameters. The effect is exactly the same as a call to the Write standard 
procedure with the same parameters, except that the resulting string is 
stored in S instead of being written to a text file. 

See also Vol, Write 

Example function lntToStr(I: Longint) : String; 
{ Convert any integer type to a string } 
var 

S: string[ll]; 
begin 

Str (I, S); 

IntToStr := S; 
end; 
begin 

Writeln (IntToStr (-5322) ) ; 
end. 



Succ function 



Function Returns the successor of the argument. 
Declaration succ (X) 
Result type Same type as parameter. 

Remarks X is an ordinal-type expression. The result, of the same type as X, is the 
successor of X. 



See also Inc, Fred 
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Swap function 



Swap function 



Function Swaps the high- and low-order bytes of the argument. 

Declaration swap (X) 

Result type Same type as parameter. 

Remarks X is an expression of type Integer or Word. 

See also Hi, Lo 

Example var 

X: Word; 
begin 

X := Swap ($1234); { $3412 } 
end. 



SwapVectors procedure 



Dos 



Function Swaps interrupt vectors. 

Declaration SwapVectors 

Remarks Swaps the contents of the SavelntXX pointers in the System unit with the 
current contents of the interrupt vectors. SwapVectors is typically called 
just before and just after a call to Exec. This ensures that the Exec'd process 
does not use any interrupt handlers installed by the current process and 
vice versa. 

See also Exec 

Example { $ M 8192, 0,0} 
uses Dos; 
var 

Command : string [79]; 
begin 

Write ('Enter DOS command: '); 

Readln (Command) ; 

if Command <> ' ' then 
Command: = '/C ' + Command; 

SwapVectors; 

Exec (GetEnv (' COMSPEC ) , Command) ; 

SwapVectors; 

if DosError <> then 
WritelnC Could not execute C0MMAND.COM'); 
end. 
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TextBackground procedure 



Crt 



Function 

Declaration 

Remarks 



Selects the background color. 

TextBackground (Color: Byte); 

Color is an integer expression in the range 0..7, corresponding to one of the 
first eight color constants: 



const 

Black 

Blue 

Green 

Cyan 

Red 

Magenta 

Brown 

LightGray 



= 
= 1 
= 2 
= 3 
= 4 
= 5 
= 6 
= 7 



See also 



There is a byte variable in Crt — TextAttr — that is used to hold the current 
video attribute. TextBackground sets bits 4-6 of TextAttr to Color. 

The background of all characters subsequently written will be in the 
specified color. 

HighVideo, LowVideo, NormVideo, TextColor 



TextColor procedure 



Crt 



Function Selects the foreground character color. 

Declaration TextColor (Color: Byte) 

Remarks Color is an integer expression in the range 0..15, corresponding to one of 
the color constants defined in Crt: 



const 




Black 


= 


Blue 


= 1 


Green 


= 2 


Cyan 


= 3 


Red 


= 4 


Magenta 


= 5 


Brown 


= 6 


LightGray 


= 7 


DarkGray 


= 8 


LightBlue 


= 9 
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TextColor procedure 



LightGreen = 10 
Light Cyan =11 
LightRed = 12 
LightMagenta =13 
Yellow = 14 
White = 15 

There is a byte variable in Crt — TextAttr — that is used to hold the current 
video attribute. TextColor sets bits 0-3 to Color. If Color is greater than 15, 
the blink bit (bit 7) is also set; otherwise, it is cleared. 

You can make characters blink by adding 128 to the color value. The Blink 
constant is defined for that purpose; in fact, for compatibility with Turbo 
Pascal 3.0, any Color value above 15 causes the characters to blink. The 
foreground of all characters subsequently written will be in the specified 
color. 



See also HighVideo, LowVideo, NormVideo, TextBackground 

Example TextColor (Green) ; 

TextColor (LightRed + Blink) ; 
TextColor (14); 



{ Green characters } 

{ Blinking light-red characters } 

{ Yellow characters } 



TextHeight function 



Graph 



Function Returns the height of a string in pixels. 

Declaration TextHeight (TextString: String) 

Result type Word 

Remarks Takes the current font size and multiplication factor, and determines the 
height of TextString in pixels. This is useful for adjusting the spacing 
between lines, computing viewport heights, sizing a title to make it fit on 
a graph or in a box, and more. 

For example, with the 8x8 bit-mapped font and a multiplication factor of 1 
(set by SetTextStyle), the string Turbo is 8 pixels high. 

It is important to use TextHeight to compute the height of strings, instead 
of doing the computation manually. In that way, no source code modifi- 
cations have to be made when different fonts are selected. 

Restrictions Must be in graphics mode. 

See also OutText, OutTextXY, SetTextSh/le, SetUserCharSize, TextWidth 



156 



Turbo Pascal Library Reference 



TextHeight function 



Example use s Graph; 
vair 

Gd, Gm: Integer; 
Y, Size: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
Y := 0; 

for Size := 1 to 5 do 
begin 

SetTextStyle(DefaultFont, HorizDir, Size); 

OutTextXY(0, Y, 'Turbo Graphics'); 

Inc(Y, TextHeight ('Turbo Graphics')); 
end; 
Readln; 
CloseGraph; 
end. 



TextMode procedure 



Crt 



Function Selects a specific text mode. 

Declaration TextMode (Mode: Word) 

Remarks The following constants are defined: 

{ 40x25 B/W on color adapter 

{ 80x25 B/W on color adapter 

{ 80x25 B/W on monochrome adapter 

{ 40x25 color on color adapter 

{ 80x25 color on color adapter 

{ For EGA/VGA 43 and 50 line 

{ For 3.0 compatibility 

{ For 3.0 compatibility 

Other values cause TextMode to assume C80. 

When TextMode is called, the current window is reset to the entire screen, 
DirectVideo is set to True, CheckSnow is set to True if a color mode was 
selected, the current text attribute is reset to normal corresponding to a 
call to NormVideo, and the current video is stored in LastMode. In addition, 
LastMode is initialized at program startup to the then-active video mode. 



const 




BW40 = 




BW80 = 2 




Mono = 7 




CO40 = 1 




CO80 = 3 




Font8x8 = 256; 


C40 = CO40; 


C80 = CO80 
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TextMode procedure 



Specifying TextMode(LastMode) causes the last active text mode to be re- 
selected. This is useful when you want to return to text mode after using a 
graphics package, such as Graph or Graph3. 

The following call to TextMode: 

TextMode (C80 + Font8x8) 

will reset the display into 43 lines and 80 columns on an EGA, or 50 lines 
and 80 columns on a VGA with a color monitor. TextMode(Lo(LastMode)) 
always turns off 43- or 50-line mode and resets the display (although it 
leaves the video mode unchanged); while 

TextMode (Lo(LastMode) + Font8x8) 

will keep the video mode the same, but reset the display into 43 or 50 
lines. 

If your system is in 43-line mode when you load a Turbo Pascal program, 
the mode will be preserved by the Crt startup code, and the window 
variable that keeps track of the maximum number of lines on the screen 
( WindMax) will be initialized correctly. 

Here's how to write a "well-behaved" program that will restore the video 
mode to its original state: 

program Video; 
uses Crt; 
var 

OrigMode: Integer; 
begin 

OrigMode := LastMode; { Remember original mode } 

TextMode (OrigMode) ; 
end. 

Note that TextMode does not support graphics modes, and therefore 
TextModeiOrigMode) will only restore those modes supported by 
TextMode. 



See also RestoreCrtMode 
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TextWidth function 



Graph 



Function Returns the width of a string in pixels. 

Declaration TextWidth (TextString: String) 

Result type Word 

Remarks Takes the string length, current font size, and multiplication factor, and 
determines the width of TextString in pixels. This is useful for computing 
viewport widths, sizing a title to make it fit on a graph or in a box, and so 
on. 

For example, with the 8x8 bit-mapped font and a multiplication factor of 1 
(set by SetTextStyle), the string Turbo is 40 pixels wide. 

It is important to use TextWidth to compute the width of strings, instead of 
doing the computation manually. In that way, no source code 
modifications have to be made when different fonts are selected. 

Restrictions Must be in graphics mode. 

See also OutText, OutTextXY, SetTextStyle, SetUserCharSize, TextHeight 

Example US6 s Graph; 
var 

Gd, Gm: Integer; 
Row: Integer; 
Title: String; 
Size: Integer; 
begin 

Gd := Detect; 

InitGraph (Gd, Gm, "); 

if GraphResult <> grOk then 

Halt(l); 
Row := 0; 

Title := 'Turbo Graphics'; 
Size := 1; 

while TextWidth (Title) < GetMaxX do 
begin 

OutTextXY(0, Row, Title); 

Inc (Row, TextHeight ('M' ) ) ; 

Inc(Size); 

SetTextStyle (DefaultFont, HorizDir, Size) ; 
end; 
Readln; 
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Trunc function 



CloseGraph; 
end. 



Trunc function 



Function Truncates a real-type value to an integer-type value. 
Declaration Trunc (X: Real) 

Result type Longint 

Remarks X is a real-type expression. Trunc returns a Longint value that is the value 
of X rounded toward zero. 

Restrictions A run-time error occurs if the truncated value of X is not within the 
Longint range. 

See also Round, Int 



Truncate procedure 



Function Truncates the file size at the current file position. 

Declaration Truncate (var F) 

Remarks F is a file variable of any type. All records past F are deleted and the 
current file position also becomes end-of-file (Eo/CF) is True). 

If I/O-checking is off, the IOResult function returns a nonzero value if an 
error occurs. 

Restrictions F must be open. Truncate does not work on text files. 

See also Reset, Rewrite, Seek 



TypeOf function 



Function Returns a pointer to an object's virtual method table. 

Declaration TypeOf(X: object) 

Result type Pointer 

Remarks X is any object type that declares or inherits virtual methods. 

Restrictions If X has no virutal methods, a compiler error occurs. 
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UnpackTime procedure 



Dos 



Function Converts a 4-byte, packed date-and-time Longint returned by GetFTime, 
FindFirst, or FindNext into an unpacked DateTime record. 

Declaration UnpackTime (Time: Longint; var DT: DateTime) 

Remarks DateTime is a record declared in the Dos unit: 

DateTime = record 

Year, Month, Day, Hour, Min, Sec: Word 
end; 

The fields of the Time record are not range-checked. 

See also GetFTime, GetTime, PackTime, SetFTime, SetTime 



UpCase function 



Function Converts a character to uppercase. 
Declaration UpCase(Ch: Char) 

Result type Char 

Remarks Ch is an expression of type Char. The result of type Char is Ch converted 
to uppercase. Character values not in the range a..z are unaffected. 



Vol procedure 



Function Converts the string value to its numeric representation. 

Declaration Val(S: String; var V; var Code: Integer) 

Remarks S is a string-type expression. V is an integer-type or real-type variable. 
Code is a variable of type Integer. S must be a sequence of characters that 
form a signed whole number according to the syntax shown in the section 
"Numbers" in Chapter 1 of the Programmer's Guide. Vol converts S to its 
numeric representation and stores the result in V. If the string is somehow 
invalid, the index of the offending character is stored in Code; otherwise, 
Code is set to zero. 

Vol performs range-checking differently depending on the state of {$R} 
and the type of the parameter V. 
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Val procedure 



With range-checking on, {$R+}, an out-of-range value always generates a 
run-time error. With range-checking off, {$R-}, the values for an out-of- 
range value vary depending upon the data type of V. If V is a Real or 
Longint type, the value of V is undefined and Code returns a nonzero 
value. For any other numeric type, Code returns a value of zero, and V will 
contain the results of an overflow calculation (assuming the string value is 
within the long integer range). 

Therefore, you should pass Val a Longint variable and perform range- 
checking before making an assignment of the returned value: 

{$R-} 

Val ('65536', LonglntVar, Code) 

if (Code <> 0) or LonglntVar < 0) or (LonglntVar > 65535) then 



{ Error } 



else 

WordVar := LonglntVar; 



In this example, LonglntVar would be set to 65,536, and Code would equal 
0. Because 65,536 is out of range for a Word variable, an error would be 
reported. 

Restrictions Trailing spaces must be deleted. 

See also Sir 

Example V ar I, Code: Integer; 
begin 

{ Get text from command line } 
Val(ParamStr(l), I, Code); 
{ Error during conversion to integer? } 
if code <> then 

Writeln ('Error at position: ', Code) 
else 
Writeln ('Value = ', I); 
end. 



WhereX function 



Crt 



Function Returns the X-coordinate of the current cursor position, relative to the 
current window. 

Declaration wherex 

Result type Byte 

See also GotoXY, WhereY, Window 
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WhereY function 



WhereY function 



Crt 



Function Returns the Y-coordinate of the current cursor position, relative to the 
current window. 



Declaration WhereY 
Result type Byte 
See also GotoXY, WhereX, Window 



Window procedure 



Crt 



Function Defines a text window on the screen. 

Declaration Window (XI, Yl, X2, Y2: Byte) 

Remarks XI and Yl are the coordinates of the upper left corner of the window, and 
XI and Y2 are the coordinates of the lower right corner. The upper left 
corner of the screen corresponds to (1, 1). The minimum size of a text 
window is one column by one line. If the coordinates are in any way 
invalid, the call to Window is ignored. 

The default window is (1, 1, 80, 25) in 25-line mode, and (1, 1, 80, 43) in 
43-line mode, corresponding to the entire screen. 

All screen coordinates (except the window coordinates themselves) are 
relative to the current window. For instance, GotoXYiX, 1) will always 
position the cursor in the upper left corner of the current window. 

Many Crt procedures and functions are window-relative, including ClrEol, 
ClrScr, DelLine, GotoXY, InsLine, WhereX, WhereY, Read, Readln, Write, 
Writeln. 

WindMin and WindMax store the current window definition (refer to the 
"WindMin and WindMax" section in Chapter 15 of the Programmer's 
Guide). A call to the Window procedure always moves the cursor to (1, 1). 

See also ClrEol, ClrScr, DelLine, GotoXY, WhereX, WhereY 

Example uses crt; 
var 

X, Y: Byte; 
begin 

TextBackground (Black) ; { Clear screen } 
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Window procedure 



ClrScr; 
repeat 

X := Succ (Random (80)); 

Y := Succ (Random (25)); 

Window(X, Y, X + Random(lO), Y + Random(8)); 

TextBackground(Random(16) ) ; 

ClrScr; 
until KeyPressed; 
end. 



{ Draw random windows } 



{ In random colors } 



Write procedure (text files) 



Function Writes one or more values to a text file. 

Declaration Write ( [ var F: Text; ] VI [, V2,...,VW ] ) 

Remarks F, if specified, is a text-file variable. If F is omitted, the standard file 
variable Output is assumed. Each P is a write parameter. Each write 
parameter includes an output expression whose value is to be written to 
the file. A write parameter can also contain the specifications of a field 
width and a number of decimal places. Each output expression must be of 
a type Char, Integer, Real, string, packed string, or Boolean. 

A write parameter has the form 

OutExpr [: MinWidth [: DecPlaces ] ] 

where OutExpr is an output expression. MinWidth and DecPlaces are type 
integer expressions. 

MinWidth specifies the minimum field width, which must be greater than 
0. Exactly MinWidth characters are written (using leading blanks if neces- 
sary) except when OutExpr has a value that must be represented in more 
than MinWidth characters. In that case, enough characters are written to 
represent the value of OutExpr. Likewise, if MinWidth is omitted, then the 
necessary number of characters are written to represent the value of 
OutExpr. 

DecPlaces specifies the number of decimal places in a fixed-point represen- 
tation of a type Real value. It can be specified only if OutExpr is of type 
Real, and if MinWidth is also specified. When MinWidth is specified, it 
must be greater than or equal to 0. 

Write with a type Char value: li MinWidth is omitted, the character value 
of OutExpr is written to the file. Otherwise, MinWidth - 1 blanks followed 
by the character value of OutExpr is written. 
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Write procedure (text files) 



Table 1.1 

Components of the 

output string 



Table 1.2 

Components of the 

fixed-point string 



Write with a type integer value: If MinWidth is omitted, the decimal 
representation of OutExpr is written to the file with no preceding blanks. 
If MinWidth is specified and its value is larger than the length of the 
decimal string, enough blanks are written before the decimal string to 
make the field width MinWidth. 

Write with a type real value: If OutExpr has a type real value, its decimal 
representation is written to the file. The format of the representation 
depends on the presence or absence of DecPlaces. 

If DecPlaces is omitted (or if it is present, but has a negative value), a 
floating-point decimal string is written. If MinWidth is also omitted, a 
default MinWidth of 17 is assumed; otherwise, if Min Width is less than 8, it 
is assumed to be 8. The format of the floating-point string is 

[ | - ] <digit> . <decimals> E [ + | - ] <exponent> 

The components of the output string are shown in Table 1.1: 

[ I - ] " " or "-", according to the sign of OutExpr 

<digit> Single digit, "0" onl^-if OutExpr is 

<decimals> Digit string of Min Width-7 (but at most 10) digits 

E Uppercase [E] character 

[ + I - 1 According to sign of exponent 

<exponent> Two-digit decimal exponent 

If DecPlaces is present, a fixed-point decimal string is written. If DecPlaces 
is larger than 11, it is assumed to be 11. The format of the fixed-point 
string follows: 

[ <blanks> ] [ - ] <digits> [ . <decimals> ] 

The components of the fixed-point string are shown in Table 1.2: 

[ <blanks> ] Blanks to satisfy T : Min Width 

[-] If OutExpr is negative 

<digits> At least one digit, but no leading zeros 

[ . <decimals> ] Decimals if DecPlaces > 

Write with a string-type value: If MinWidth is omitted, the string value of 
OutExpr is written to the file with no leading blanks. If MinWidth is 
specified, and its value is larger than the length of OutExpr, enough 
blanks are written before the decimal string to make the field width 
MinWidth. 
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Write procedure (text files) 



Restrictions 
See also 



Write with a packed string-type value: If OutExpr is of packed string type, 
the effect is the same as writing a string whose length is the number of 
elements in the packed string type. 

Write with a Boolean value: If OutExpr is of type Boolean, the effect is the 
same as writing the strings True or False, depending on the value of 
OutExpr. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

File must be open for output. 

Read, Readln, Writeln 



Write procedure (typed files) 



Function Writes a variable into a file component. 

Declaration write (f, vi [, V2,...,w] ) 

Remarks F is a file variable, and each V is a variable of the same type as the 

component type of F. For each variable written, the current file position is 
advanced to the next component. If the current file position is at the end 
of the file — that is, if Eof(F) is True — the file is expanded. 

With {$1-}, IOResult returns a if the operation was successful; otherwise, 
it returns a nonzero error code. 

See also Writeln 



Writeln procedure 



Function Executes the Write procedure, then outputs an end-of-line marker to the 
file. 

Declaration Writeln ( [ var F: Text; ] VI [, V2, ...,VW] ) 

Remarks Writeln procedure is an extension to the Write procedure, as it is defined 
for text files. After executing the Write, Writeln writes an end-of-line 
marker (carriage-return/line-feed) to the file. 

Writeln(F) with no parameters writes an end-of-line marker to the file. 
(Writeln with no parameter list altogether corresponds to Writeln(Output).) 
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Writeln procedure 



Restrictions File must be open for output. 
See also Write 
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N 



D 



X 



$ See compiler directives 
@ (address-of) operator See address-of i 
operator 

A 

Abs function 4 
Addr function 4 
address-of (@) operator 

versus Addr 4 
AndPut constant 104 
Append procedure 5 
Arc procedure 6 
ArcTan function 6 
aspect ratio 43 

correction factor, changing 126 
Assign procedure 7 
AssignCrt procedure 8 

B 

Bar3D procedure 9 
Bar procedure 8 
BGI, Zenith Z-449 and 74 
BINOBJ 112, 113 
bit images 54 
BitBlt operations 104 
BlockRead procedure 10 
Block Write procedure 1 1 
buffers, flushing 39 



ChDir procedure 12 
Chr function 13 
Circle procedure 13 
ClearDevice procedure 14 
clearing the overlay buffer 96 
ClearViewPort procedure 14 
clipping parameters 64 



Close procedure 15 

CloseGraph procedure 16 

ClrEol procedure 16 

ClrScr procedure 17 

colors 50, 51 
background 44 
drawing 45 

command-line parameters 101 

compiler directives 
$187 
$M 81, 87, 88, 100 

Concat function 17 

CONFIG.SYS 98 

Copy function 18 

Cos function 18 

Crt unit 

AssignCrt procedure 8 
ClrEol procedure 16 
ClrScr procedure 17 
Delay procedure 20 
DelLine procedure 20 
GotoXY procedure 67 
High Video procedure 71 
InsLine procedure 75 
KeyPressed function 82 
LowVideo procedure 86 
NormVideo procedure 92 
NoSound procedure 92 
ReadKey function 709 
Sound procedure 757 
TextBackground procedure 755 
TextColor procedure 755 
TextMode procedure 757 
WhereX function 162 
WhereY function 163 
Window procedure 753 

CS register 19 

CSeg function 19 
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cursor position 
reading 162, 163 
setting 67 



date and time procedures 

GetDate 46 

GetFTime 52 

GetTime 63 

SetDate 129 

SetFTime 133 

SetTime 144 
Dec procedure 19 
Delay procedure 20 
Delete procedure 20 
DelLine procedure 20 
DetectGraph procedure 21 
devices 14 

drivers, installing 76 
directives See compiler, directives 
directories 47 

changing 12 

procedures 120 

searching 36, 40 
DiskFree function 22 
disks, space 22 
DiskSize function 22 
Dispose procedure 23 
DOS 

Pascal functions for 91 

verify flag 64 
setting 146 
Dos unit 

DiskFree function 22 

DiskSize function 22 

DosExitCode function 24 

Dos Version function 24 

EnvCount function 27 

EnvStr function 27 

Exec procedure 30 

FExpand function 32 

FindFirst procedure 36 

FindNext procedure 37 

FSearch function 40 

FSplit procedure 41 

GetCBreak procedure 45 

GetDate procedure 46 



GetEnv function 48 

GetFAttr procedure 49 

GetFTime procedure 52 

GetlntVec procedure 55 

GetTime procedure 63 

GetVerify procedure 64 

Intr procedure 80 

Keep procedure 81 

MsDos procedure 91 

PackTime procedure 100 

SetCBreak procedure 128 

SetFTime procedure 133 

SetlntVec procedure 136 

SetTime procedure 144 

SetVerify 146 

Swap Vectors procedure 154 

UnpackTime procedure 161 
DosError variable 30, 36, 37, 49, 52, 130, 133 
DosExitCode function 24 
Dos Version function 24 
DrawPoly procedure 25 
drivers 

active, returning 
maximum mode number 56 
name 48 
DS register 26 
DSeg function 26 



ellipse, drawing 34 

Ellipse procedure 26 

elliptical sector, drawing and filling 121 

end of file status 28 

EnvCount function 27 

EnvStr function 27 

Eof function 28 

Eoln function 29 

Erase procedure 29 

errors 

codes for graphics operations 68 

messages 68 

run-time See run-time, errors 
Exec procedure 30 
exit 

codes 24 

procedures 31 
Exp function 32 
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FExpand function 32 
file-handling procedures 

Rename 116 

Reset 117 

Rewrite 119 

Seek 122 

SetFAttr 130 

Truncate 160 
FilePos function 33 
files 

Assign procedure 7 

attributes 49 

closing 15 

erasing 29 

untyped, variable 10,11 
FileSize function 33 
fill patterns 50 
FillChar procedure 34 
FillEllipse procedure 34 
filling areas 37 
FillPoly procedure 35 
FindFirst procedure 36 
FindNext procedure 37 
FloodFill procedure 37 
Hush procedure 39 
Font8x8 variable 157, 158 
fonts 

installing 79 

stroked 145 
Frac function 39 
fractions, returning 39 
FreeMem procedure 40 
FSearch function 40 
FSplit procedure 32, 41 
functions See specific function 



GetArcCoords procedure 42 
GetAspectRatio procedure 43 
GetBkColor function 44 
GetCBreak procedure 45 
GetColor function 45 
GetDate procedure 46 
GetDefaultPalette function 46 
GetDir procedure 47 



GetDriverName function 48 
GetEnv function 48 
GetFAttr procedure 49 
GetFillPattern procedure 50 
GetFillSettings procedure 51 
GetFTime procedure 52 
GetGraphMode function 52 
Getlmage procedure 54 
GetlntVec procedure 55 
GetLineSettings procedure 55 
GetMaxColor function 56 
GetMaxMode-function 56 
GetMaxX function 57 
GetMaxY function 58 
GetMem procedure 58 
GetModeName function 59 
GetModeRange procedure 60 
GetPalette procedure 60 

IBM 8514 and 60 
GetPaletteSize function 61 
GetPixel function 62 
GetTextSettings procedure 62 
GetTime procedure 63 
GetVerify procedure 64 
GetViewSettings procedure 64 
GetX function 65 
GetY function 66 
GotoXY procedure 67 
Graph unit 

Arc procedure 6 
Bar3D procedure 9 
Bar procedure 8 
Circle procedure 13 
ClearDevice procedure 14 
ClearViewPort procedure 14 
CloseGraph procedure 16 
DetectGraph procedure 21 
DrawPoly procedure 25 
Ellipse procedure 26 
FillEllipse procedure 34 
FillPoly procedure 35 
FloodFill procedure 37 
GetArcCoords procedure 42 
GetAspectRatio procedure 43 
GetBkColor function 44 
GetColor function 45 
GetDefaultPalette function 46 
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GetDriverName function 48 
GetFillPattern procedure 50 
GetFillSettings procedure 51 
GetGraphMode function 52 
Getlmage procedure 54 
GetLineSettings procedure 55 
GetMaxColor function 56 
GetMaxMode function 56 
GetMaxX function 57 
GetMaxY function 58 
GetModeName function 59 
GetModeRange procedure 60 
GetPalette procedure 60 
GetPaletteSize function 61 
GetPixel function 62 
GetTextSettings procedure 62 
GetViewSettings procedure 64 
GetX function 65 
GetY function 66 
GraphDefaults procedure 67 
GraphErrorMsg function 68 
GraphResult function 68 
ImageSize function 71 
InitGraph procedure 73 
InstallUserDriver function 76 
InstallUserFont function 79 
Line procedure 83 
LineRel procedure 84 
LineTo procedure 84 
MoveRel procedure 89 
MoveTo procedure 90 
OutText procedure 93 
OutTextXY procedure 95 
PieSlice procedure 102 
Putlmage procedure 104 
PutPixel procedure 106 
Rectangle procedure 111 
RegisterBGIdriver function 1 12 
RegisterBGIfont function 1 13 
RestoreCrtMode procedure 1 18 
Sector procedure 121 
SetActivePage procedure 724 
SetAllPalette procedure 125 
SetAspectRatio procedure 126 
SetBkColor procedure 727 
SetColor procedure 129 
SetFillPattern procedure 730 



SetFiUStyle procedure 732 

SetGraphBufSize procedure 733 

SetGraphMode procedure 734 

SetLineStyle procedure 136 

SetPalette procedure 737 

SetRGBPalette procedure 739 

SetTextJustify procedure 742 

SetTextStyle procedure 743 

SetUserCharSize procedure 745 

SetViewPort procedure 746 

SetVisualPage procedure 748 

SetWriteMode 749 

TextHeight function 756 

TextWidth function 759 
GraphDefaults procedure 67 
GraphDriver variable 

IBM 8514 and 74 
GraphErrorMsg function 68 
graphics 

bit-image operations 764 

cards 27, 73 

drawing operations 83, 84, 102, 111, 136 

drivers 73 

fill operations 730, 732 

mode 52, 73, 83, 84, 85 

page operations 724, 748 

palette operations 725, 727, 729, 737 

plotting operations 706 

pointer operations 90 

polygons, drawing 25 

resolution 43 

system operations 734 

text operations 93, 95, 142, 156 

video mode operations 7 78 

viewport operations 746 
GraphMode procedure 73 
GraphResult function 68 

error codes 68 
grError 69 
grlnvalidFont 69 
grlnvalidFonfNum 69 
grIOerror 69 

H 

Halt procedure 70 

handles, DOS 7 

heap management procedures 7 76 
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Hi function 70 
high 

intensity characters 71 

order bytes 70 
High Video procedure 71 

I 

$1 compiler directive 81 

I/O 

checking 81 
DOS standard 7 

IBM 8514 

GetPalette procedure and 60 
GraphDriver variable and 74 
InitGraph procedure and 74 
palette entries, modifying 139 
SetAllPalette procedure and 126 
SetPalette procedure and 138 

ImageSize function 71 

Inc procedure 72 

InitGraph procedure 73 
SetGraphMode and 134 

input, DOS standard 7 

Insert procedure 75 

inserting 
lines 75 
strings 75 

InsLine procedure 75 

InstallUserDriver function 76 

InstallUserFont function 79 

Int function 79 

interrupt 

procedures 136 
vectors 55 
swapping 154 

Intr procedure 80 

IOResult function 80 



justification, font 62 

K 

Keep procedure 81 
keyboard operations 82, 109 
KeyPressed function 82 



Length function 82 
line 

drawing, setting writing mode for 149 

settings 55 
Line procedure 83 
LineRel procedure 84 
LineTo procedure 84 
Ln function 85 
Lo function 86 
LowVideo procedure 86 

M 

$M compiler directive 81, 87, 88, 100 

Mark procedure 86 

MaxAvail function 87 

MemAvail function 88 

memory 40, 58 

MkDir procedure 88 

Move procedure 89 

MoveRel procedure 89 

MoveTo procedure 90 

MsDos procedure 91 

N 

New procedure 91 
extended syntax 
constructor passed as parameter 91 
NormalPut constant 104 
NormVideo procedure 92 
NoSound procedure 92 
NotPut constant 104 

o 

Odd function 92 
Ofs function 93 
Ord function 93 
OrPut constant 104 
output, DOS standard 7 
OutText procedure 93 
OutTextXY procedure 95 
Overlay unit 

OvrClearBuf procedure 96 

OvrGetBuf function 97 

Ovrlnit procedure 97 
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OvrlnitEMS procedure 98 
OvrSetBuf procedure 99 
overlays 
buffers 
clearing 96 
size 
returning 97 
setting 99 
files 
loading into EMS 98 
opening 97 
manager, initializing 97 
OvrClearBuf procedure 96 
OvrGetBuf function 97 
Ovrlnit procedure 97 
OvrlnitEMS procedure 98 
OvrSetBuf procedure 99 



PackTime procedure 100 
palette 

color lookup table, returning size 61 

definition record 46 
ParamCount function 100 
parameters, command-line 101 
ParamStr function 101 
Pi function 101 
PieSlice procedure 102 
pixel values 62 
polygons, drawing 25 
Pos function 102 
Pred function 103 
procedures See specific procedure 
process-handling routines 81 
programs 

execution, stopping 121 

halting 70 
Ptr function 103 
Putlmage procedure 104 
PutPixel procedure 106 



Random function 107 
Randomize procedure 107 
range-checking, Val and 161 



Read procedure 

text files 108 

typed files 109 
reading records 10 
ReadKey function 109 
Readln procedure 110 
Rectangle procedure 111 
RegisterBGIdriver function 7 12 
RegisterBGIfont function 1 13 
registers, CS 19 
Release procedure 1 16 
Rename procedure 116 
Reset procedure 117 
resolution, graphics 43 
RestoreCrtMode procedure 1 18 
Rewrite procedure 119 
RmDir procedure 120 
Round function 120 
run-time errors, generating 121 
RunError procedure 121 



searching directories 36 
Sector procedure 121 
Seek procedure 122 
SeekEof function 123 
SeekEoln function 123 
Seg function 124 
SetActivePage procedure 124 
SetAllPalette procedure 125 

IBM 8514 and 126 
SetAspectRatio procedure 126 
SetBkColor procedure 127 
SetCBreak procedure 128 
SetColor procedure 129 
SetDate procedure 129 
SetFAttr procedure 130 
SetFillPattern procedure 130 
SetFillStyle procedure 132 
SetFTime procedure 133 
SetGraphBufSize procedure 133 
SetGraphMode procedure 734 
SetlntVec procedure 136 
SetLineStyle procedure 136 
SetPalette procedure 737 

IBM 8514 and 738 
SetRGBPalette procedure 739 
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SetTextBuf procedure 140 
SetTextJustify procedure 142 
SetTextStyle procedure 143 

OutText and 93 

OutTextXY and 95 
SetTime procedure 144 
SetUserCharSize procedure 145 
SetVerify procedure 146 
SetViewPort procedure 146 
SetVisualPage procedure 148 
SetWriteMode procedure 149 
Sin function 150 
SizeOf function 34, 151 
software interrupts 80 
sound operations 

NoSound 92 

Sound 151 
Sound procedure 151 
SPtr function 152 
Sqr function 152 
Sqrt function 152 
SSeg function 152 
Str procedure 153 
strings 

concatenation 17 

construction 17 

deletion 20 

initializing 34 

length byte 34 

procedures 75, 153, 161 
stroked fonts 145 
substrings 

copying 18 

deleting 20 

inserting 75 

position 102 
Succ function 153 
Swap function 154 
Swap Vectors procedure 154 



terminating a program 31 
text 

attributes 62 

files 28 
TextAttr variable 

ClrEoland 16 



ClrScrand 17 

High Video and 71 

LowVideo and 86 

NormVideo and 92 

TextBackground and 755 

TextColorand 156 
TextBackground procedure 755 
TextColor procedure 755 
TextHeight function 156 
TextMode procedure 757 
TextWidth function 759 
time procedures 

GetFTime 52 

GetTime 63 

SetFTime 733 

SetTime 744 
Trunc function 750 
Truncate procedure 750 
Turbo Pascal 3.0 

conversion, chaining 757 
TypeOf function 750 

u 

UnpackTime procedure 757 
untyped files, variable 70, 7 7 
UpCase function 757 

V 

Val procedure 757 
variables 

disposing of 23, 40 

DosError 30,36, 37, 49, 52, 130, 133 

increasing 72 

untyped file 70, 77 
VGA 

driver, modifying palette entries for 730 

modes 27 
emulated 74 
VGAHi 53, 135 
VGALo 53, 135 
VGAMed 53, 135 
video operations 

AssignCrt 8 

ClrEol 75 

ClrScr 17 

DelLine procedure 20 
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GotoXY 67 
HighVideo 71 
InsLine 75 
LowVideo 86 
NormVideo 92 
RestoreCrtMode 118 
TextBackground 155 
TextColor 155 
WhereX 762 
WhereY 163 
Window 163 
Write (text) 164 
Write (typed) 166 
Writeln/66 
viewports 14 
parameter 64 



w 

WhereX function 162 
WhereY function 163 
Window procedure 163 
Write procedure 

text files 164 

typed files 166 
write statements, DOS 7 
Writeln procedure 166 
writing records 11 



XORPut constant 104 



Zenith Z-449, BGI and 74 
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